Create an authentication token

post

https://{environment}.joinforage.app/o/token/

Use Session Tokens In Production

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.

Managing OAuth Token Expiration

OAuth tokens expire after 7 days by default (604800 seconds), but can be configured to expire sooner or up to 30 days. There can be up to 1000 active authentication 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.

Authentication Guide

Check out the Forage authentication guide for more details on authentication tokens.

A POST request to /o/token/ creates a new authentication token. The token is returned as the access_token value in the response body.

An authentication token is a long-lived OAuth 2.0 bearer token that validates requests from your backend to Forage. Pass an authentication token in the Authorization header of server-side requests to handle sensitive tasks like creating an order or capturing a payment.

You need your app's Client ID and Client Secret from the Forage dashboard (sandbox, production) to generate an authentication token. If you don't yet have dashboard access, then please get in touch.

Form Data

Request payload body for server to issue an access token

expiration_time

integer

Defaults to 604800

The lifespan of the token in seconds. The acceptable range includes 86400 (one day) to 2592000 (30 days).

Defaults to 604800 (7 days), if not set.

grant_type

string

required

The constant string client_credentials.

scope

string

Defaults to hosted_checkout

The token’s permissions level. Possible values include:

accounts: This scope is most useful to platforms that support multiple merchants. Use accounts to manage merchant-related data, for example to create a Session to onboard a new merchant via the /accounts/merchants/onboarding_session/ endpoint.
hosted_checkout: Use this scope for Fully Hosted integrations. Creates a token that only grants access to create Fully Hosted Sessions. The default scope.
pinpad_only: Use this scope for Custom and SDK integrations. The most permissive token scope. Creates a token that grants access to start Sessions that collect a customer’s EBT Card PIN, and to perform all operations that a customer’s PIN authorizes, including creating payments and payment methods.
reporting: The scope required to query/reporting/ endpoints.

To create a token with multiple scopes, separate scope names with a space, for example: hosted_checkout reporting.

Headers

Authorization

string

required

An OAuth 2.0 credential that validates the request. Pass the the Client ID and Client Secret from the Forage dashboard, separated by a colon, as in <client_id>:<client_secret>, through a base64 encoding function. Send this encoded value in the header of the request after the word Basic, as in Basic <encoded_credentials>.

Responses

200OK - Success

400Bad request - The request was not accepted because of an error in the request body or path.

401Unauthorized