--- updatedAt: 2026-09-11T16:56:47.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Create a session token > 📘 Authentication Guide > > For comprehensive details about authenticating with the Forage API, refer to the [authentication guide](doc:authentication). > 📘 Session Token Length > > Session tokens are short-lived and expire after fifteen minutes. > ⚠️ Authentication Token Required > > You need to create an [authentication token](ref:create-authentication-token) before you can generate a session token. A `POST` request to `/session_token/` creates a new session token. The token is returned as the `token` value in the response body. A session token is a temporary OAuth 2.0 bearer token that expires after 15 minutes. Session tokens are used in client-side requests. For example, `POST`s to [create a Payment Method](ref:create-payment-method) require session tokens in the `Authorization` header, and session tokens are passed as parameters to [SDK methods](doc:authentication#sdk-methods-that-require-session-tokens) that submit customer data. You can optionally include a `customer_id` in the request body. This should be the same `customer_id` you pass when creating a [PaymentMethod](ref:create-payment-method) for the same customer, so Forage can associate the two. # OpenAPI definition ```json { "openapi": "3.0.0", "x-readme": { "explorer-enabled": false, "proxy-enabled": false }, "info": { "title": "Forage Payments API", "description": "The Forage Payments API is a REST API for processing Electronic Benefits Transfer (EBT) payments (SNAP and EBT Cash) in your e-commerce or in-store application.\n\nProcessing any EBT payment, or checking an EBT card's balance, requires the cardholder's PIN. Federal regulations require all PIN entry to happen through a PCI-compliant, USDA-approved interface. Forage provides that interface, so EBT PIN collection always happens through a Forage-hosted surface (Forage Checkout or a Forage SDK), never directly in your own form. Some endpoints (for example, capture and balance) are only reachable through that surface because they require PIN data in the request.\n\nEBT rarely covers an entire order: items like delivery fees and non-eligible products can't be paid with SNAP or EBT Cash. You decide how to handle the remaining balance (split tender) and any credit or debit processing alongside the EBT portion.\n\nForage offers four integration options. Pick the one that fits your platform and engineering resources:\n\n1. **Fully Hosted Checkout.** Forage processes EBT and credit/debit through a Forage-hosted Checkout UI. Lowest engineering effort, and Forage absorbs most error handling. See the [Fully Hosted Checkout guide](https://docs.joinforage.app/docs/fully-hosted).\n2. **Custom Checkout.** Forage processes EBT; you handle split tender, taxes, and credit/debit in your own checkout flow. Best when you want minimal changes to your existing UX. See the [Custom Checkout guide](https://docs.joinforage.app/docs/custom).\n3. **Online SDKs.** Client-side SDKs for [web](https://docs.joinforage.app/docs/forage-js), [iOS](https://docs.joinforage.app/docs/ios), and [Android](https://docs.joinforage.app/docs/android) that collect EBT PINs in your app while keeping you out of PCI scope.\n4. **POS Terminal SDK.** Accept in-person EBT payments on an Android POS device. See the [POS Terminal guide](https://docs.joinforage.app/docs/forage-terminal-android).\n\nAs a general principle, any data created by your requests, or by your customers on a Forage-hosted surface, is retrievable through GET requests to the appropriate resource.\n\nHave more questions? Use our [contact form](https://www.joinforage.com/get-in-touch) to reach our sales and engineering support teams.\n", "contact": { "name": "API Support", "email": "engineering@joinforage.com" }, "version": "2025-08-04" }, "externalDocs": { "description": "Forage documentation", "url": "https://docs.joinforage.app/" }, "servers": [ { "url": "https://{environment}.joinforage.app", "variables": { "environment": { "default": "api.sandbox", "enum": [ "api", "api.sandbox" ] } } } ], "security": [], "paths": { "/api/session_token/": { "parameters": [ { "$ref": "#/components/parameters/AuthenticationBearerTokenHeader" }, { "$ref": "#/components/parameters/MerchantAccountHeader" } ], "post": { "tags": [ "Bearer Tokens" ], "summary": "Create a session token", "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request POST \\\n --url https://api.sandbox.joinforage.app/api/session_token/ \\\n --header 'Authorization: Bearer ' \\\n --header 'Merchant-Account: ' \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '\n{\n \"customer_id\": \"cus_1234567890\"\n}\n'\n" } ] }, "description": "> 📘 Authentication Guide\n>\n> For comprehensive details about authenticating with the Forage API, refer to the [authentication guide](https://docs.joinforage.app/docs/authentication).\n\n> 📘 Session Token Length\n>\n> Session tokens are short-lived and expire after fifteen minutes.\n\n\n> ⚠️ Authentication Token Required\n>\n> You need to create an [authentication token](https://docs.joinforage.app/reference/create-authentication-token) before you can generate a session token.\n\n\nA `POST` request to `/session_token/` creates a new session token. The token is returned as the `token` value in the response body.\n\n\nA session token is a temporary OAuth 2.0 bearer token that expires after 15 minutes.\n\n\nSession tokens are used in client-side requests. For example, `POST`s to [create a Payment Method](https://docs.joinforage.app/reference/create-payment-method) require session tokens in the `Authorization` header, and session tokens are passed as parameters to [SDK methods](https://docs.joinforage.app/docs/authentication#sdk-methods-that-require-session-tokens) that submit customer data.\n\n\nYou can optionally include a `customer_id` in the request body. This should be the same `customer_id` you pass when creating a [PaymentMethod](https://docs.joinforage.app/reference/create-payment-method) for the same customer, so Forage can associate the two.\n", "security": [], "operationId": "forage_oauth:forage_session_token", "requestBody": { "$ref": "#/components/requestBodies/SessionToken" }, "responses": { "201": { "$ref": "#/components/responses/SessionToken201" }, "401": { "description": "__Unauthorized__", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "path": "/api/session_token/", "errors": [ { "code": "invalid_token", "message": "Incorrect authentication credentials.", "source": { "resource": "OAuth_Access_Tokens", "ref": "" } } ] } } } } } } } }, "components": { "schemas": { "ErrorsArray": { "type": "array", "description": "An array with information about the error.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short string that represents the error." }, "message": { "type": "string", "description": "A developer-facing message with more details about the error, not to be displayed to customers." }, "source": { "type": "object", "properties": { "resource": { "type": "string", "description": "The type of the Forage resource involved in the error." }, "ref": { "type": "string", "description": "If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved." } } }, "details": { "type": "object", "description": "Additional details about the error, if applicable." } } }, "example": [] }, "ErrorResponseObject": { "type": "object", "description": "An object that includes details about the error.", "properties": { "path": { "type": "string", "description": "The requested endpoint." }, "errors": { "$ref": "#/components/schemas/ErrorsArray" } } }, "SessionTokenRequest": { "type": "object", "description": "Optional parameters to pass when creating a session token.\n", "properties": { "customer_id": { "type": "string", "maxLength": 64, "description": "A unique identifier for the end customer. This value allows us to scope further actions to this user.\n\nEach customer should only have one unique `customer_id` and it should be consistent across sessions.\n" } } } }, "requestBodies": { "SessionToken": { "description": "Optional parameters to pass when creating a session token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTokenRequest" } } } } }, "responses": { "SessionToken201": { "description": "__Created__ - Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The authentication token to include as the bearer token in the `Authorization` header of client-side requests and as a parameter to SDK methods.", "example": "sandbox_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjozOTYsImV4cCI6MTY4ODA4MTAzMH0.G9G97BGqEWpu3BfBo23MEVjr37ZdERplXD6cOx8BbiM" }, "expiration_date": { "type": "string", "description": "A UTC timestamp that indicates when the token expires, represented as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time string.", "example": "2023-08-02T20:07:07-07:00" } } } } } } }, "parameters": { "AuthenticationBearerTokenHeader": { "name": "Authorization", "in": "header", "description": "An OAuth 2.0 [authentication token](https://docs.joinforage.app/docs/authentication#authentication-tokens) that validates the request. Send a `POST` to the [`/o/token/`](https://docs.joinforage.app/reference/create-authentication-token) endpoint to generate an authentication token. Pass the token in this header after the word `Bearer` and a whitespace, for example `Bearer `.", "schema": { "type": "string" }, "required": true }, "MerchantAccountHeader": { "name": "Merchant-Account", "in": "header", "description": "A unique merchant ID that Forage provides during onboarding, as in `123ab45c67`. The Merchant ID can be found in the Forage [sandbox](https://dashboard.sandbox.joinforage.app/login/) or [production](https://dashboard.joinforage.app/login/) dashboard.", "schema": { "type": "string" }, "required": true } } } } ``` # Sibling pages * [Create an authentication token](https://docs.joinforage.app/reference/create-authentication-token.md) * [Revoke an authentication token](https://docs.joinforage.app/reference/revoke-authentication-token.md) * [Bulk revoke authentication tokens](https://docs.joinforage.app/reference/bulk-revoke-auth-tokens.md)