Authenticate with Forage

Authentication is the process of validating your app’s requests to the Forage Payments API. Requests use the HTTP Authorization header to verify operations. The API accepts bearer tokens in this header.

✅

You need your app’s Client ID and Client Secret from the Forage dashboard (sandbox, production) to generate bearer tokens. If you need help finding these credentials, then refer to the Register an app guide.

📘

There can be up to 1000 active bearer tokens for a Client ID and Client secret pair at any given time. To manage the number of active authentication tokens, use the /o/revoke_token/ endpoint to revoke a single token, or /o/bulk_revoke/ to revoke in bulk.

Types of Forage bearer tokens

Depending on the request, the Forage Payments API accepts either an authentication token or a session token as the bearer token.

Authentication tokens

Requests from your backend server to the Forage Payments API to manage sensitive operations — like creating payment capture sessions, orders, and refunds — all require authentication tokens in the Authorization header.

To simplify front-end development, you can also pass authentication tokens to SDK methods during the build phase.

Authentication tokens last for up to 30 days.

✅

Authentication tokens follow the OAuth 2.0 client credentials flow.

📘

The number of authentication tokens that you need depends on your server architecture. Consult with the Forage team if you need help weighing your options.

🚧

To keep your app secure, long-lived authentication tokens in production are only for server-side requests. Client-side requests in production must use session tokens.

Endpoints that require authentication tokens

• Create a Fully Hosted Checkout Session: POST /sessions/
• Create a Custom Payment Capture Session: POST /capture_sessions/
• Update an Order: POST /orders/{order_ref}/
• Cancel an Order: POST /orders/{order_ref}/cancel/
• Create a refund for an entire Order: /orders/{order_ref}/refund_all/
• Create a refund for part of an Order: POST /orders/{order_ref}/refunds/
• Retrieve all refunds for a given Order: GET /orders/{order_ref}/refunds/
• Retrieve a Refund for a given Order: GET /orders/{order_ref}/refunds/{refund_ref}
• Update a Payment Method: POST /payment_methods/{payment_method_ref}/
• Create a Payment for a given Order: POST /orders/{order_ref}/payments/
• Update an OrderPayment: POST /orders/{order_ref}/payments/{payment_ref}/
• Cancel an OrderPayment: POST /orders/{order_ref}/payments/{payment_ref}/cancel
• Update a Payment: POST /payments/{payment_ref}/
• Create a refund for a given Payment: POST /payments/{payment_ref}/refunds/
• Retrieve a report: GET /reporting/{report_type}

How to generate a Forage authentication token

🚧

To protect your application, remember to only generate authentication tokens server-side.

1. Retrieve your app’s Client ID and Client Secret from the Forage dashboard (sandbox, production). If you need help finding these credentials, then refer to the Register an app guide.
2. Send a POST request to the /o/token endpoint.

Pass the Client ID and Client Secret separated by a colon, as in <client_id>:<client_secret>, through a base64 encoding function as in one of the below examples:

$ node
> btoa('<client-id>:<client-secret>')

import base64

def encode_to_base64(input_string):
    encoded_bytes = base64.b64encode(input_string.encode('utf-8'))
    encoded_string = encoded_bytes.decode('utf-8')
    return encoded_string

encoded_string = encode_to_base64('<client-id>:<client-secret>')
print(encoded_string)

Then, in the Authorization header of the request, pass the encoded result after the word Basic, like Basic <encoded_credentials> , as in the following:

curl --request POST \
     --url https://api.sandbox.joinforage.app/o/token/ \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic <base64-encoded-client-id-secret-pair>' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode 'scope=pinpad_only' \
     --data-urlencode 'expiration_time=1728000'

✅

If you’re using curl, then you can alternatively add the flag -u <client_id>:<client_secret> to your request instead of passing the Authorization header.

cURL

curl --request POST \
     --url https://api.sandbox.joinforage.app/o/token/ \
     --header 'Accept: application/json' \
     --u '<client_id>:<client_secret>' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode 'scope=pinpad_only' \
     --data-urlencode 'expiration_time=1728000'

3. Retrieve the access_token value from the response.

{
  "access_token": "sandbox_uXpcGMAMs7hhbw9JifUuJlzUZS3zWD",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "pinpad_only"
}

The access_token value in the API response is your authentication token. You can now pass it as the bearer token in requests. For example, your Authorization header would be Bearer <authentication_token>.

Refer to the /o/token reference documentation for comprehensive details about the endpoint.

Session tokens

Front-end requests to the Forage Payments API require session tokens in the Authorization header. This includes requests forwarded from Forage SDK methods, like when a customer clicks "Pay with EBT" and submits their EBT card number, creating a Forage payment method. Every new checkout requires a new session token.

Session tokens expire after 15 minutes. This quick expiry makes them preferred for front-end operations.

SDK methods that require session tokens

Android

• tokenizeEBTCard
• checkBalance
• capturePayment

iOS

• tokenizeEBTCard
• checkBalance
• capturePayment

Forage JS

• Forage(ForageConfig)

How to generate a Forage session token

1. Generate a Forage authentication token.
2. Send a POST request to the /session_token/ endpoint:
   1. Pass the authentication token in the Authorization header.
   2. Pass the merchant's FNS number in the Merchant-Account header. Ask the merchant for their FNS number if you don't already have it handy.

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/session_token/ \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: <merchant-id>'
     --header 'Content-Type: application/x-www-form-urlencoded'

3. Retrieve the token value from the response.

{
    "token": "sandbox_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

The token value in the response is your session token. You can now pass it as the bearer token in API requests and as a parameter in SDK methods. For example, your Authorization header would be Bearer <session_token>.

Refer to the /session_token/ reference documentation for comprehensive endpoint details.

📘

Some endpoints can accept either a session token or an authentication token in the Authorization header. Consult the reference documentation for the specific endpoint to confirm what bearer token type is required.

Next steps

• Configure webhooks