Understanding Forage Authentication

This page explains how Forage bearer tokens work and when to use each type. To generate tokens, see Authenticate with Forage. For a full endpoint and SDK method list, see Authentication Token Reference.

What authentication is

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 generate these tokens using your app's Client ID and Client Secret (see Register an app if you don't have those yet).

Authentication Token Reference covers token limits and revocation rules.

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.

sequenceDiagram
    participant B as Your backend
    participant F as Forage API
    participant C as Browser / app

    B->>F: POST /o/token/ (Basic auth: Client ID + Secret)
    F-->>B: Authentication token (up to 30 days)

    B->>F: POST /session_token/ (Bearer: auth token)
    F-->>B: Session token (15 min)

    B->>C: Pass session token
    C->>F: SDK request (Bearer: session 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 and follow the OAuth 2.0 client credentials flow. The number you need depends on your server architecture; consult with the Forage team if you're unsure.

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

For the full list of endpoints that require authentication tokens, see Authentication Token Reference: Endpoints.

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.

For the full list of SDK methods that require session tokens, see Authentication Token Reference: SDK methods.

Some endpoints accept either token type (see Authentication Token Reference for per-endpoint details).

Key insights

Authentication in Forage is split by context: authentication tokens are long-lived and server-side, session tokens are short-lived and front-end. This separation keeps long-lived credentials out of client code where they could be exposed. Every new checkout requires a fresh session token; authentication tokens can be reused across requests until they expire or are revoked.

Related topics

• Authenticate with Forage. Step-by-step instructions for generating both token types.
• Authentication Token Reference. Full endpoint lists, SDK methods, and token constraints.