About

Engaging with the Payments API requires one of two authentication schemes. In the previous section Generate an authentication token an authentication token can be generated to communicate with the API. An alternate way is to generate a short term Session Token that specific API can also authenticate with.

Authentication Token vs. Session Token

An Authentication Token gives unparalleled access to the payments API for an extended duration of time. This is useful for server (merchant) side operations that can be invoked against the payments API. The merchant can generate approximately 1000 tokens with varying scopes to be used for any number of tasks reliably and safely. However, since the payments API has no notion or can authenticate against individual merchant customers, the use of authentication tokens is not recommended for client side (SDK) use since each authentication token isn't scoped to a single customer activity.

The Session Token was introduced to delegate authentication to an individual user by a client app (ie. mobile app). A client app can request a session token only from a merchant server. The merchant server, using an authentication token, delegates the request for a session token to the Payments API. This session token is then passed back to the merchant client app in order to engage with the Payments API directly. Session tokens are short lived (approx. 15 minutes). When a session token expires, the client app simply requests a new session token from the merchant API and the last attempted request can simply be replayed.

Session tokens are inextricably tied to the authentication token used to generate them. In the event of a compromise, session tokens can be collectively expired by revoking the authentication token used to generate them. If a merchant requires session tokens for different use cases, it's advised that requests for session tokens is handled by any number of different authentication tokens that the merchant server has on hand to generate them.

Authentication tokens should not be used by client applications to generate session tokens, nor should they be used to engage with the Payments API from the client. The Payments API will reject requests it detects is coming from a client app using authentication tokens.

Session Token Generation & Usage

The merchant should have already generated an appropriate authentication token which will be used to generate session tokens. Please refer to Generate an authentication token for details.
On merchant servers (only), there should be a merchant specific API used to delegate requests to the Payments API for session tokens that can then be forwarded to clients which the server has authenticated with. Requests should look like the following. Authentication with the session_token endpoint is simple, provide the Authorization header and Merchant-Account header with the authentication_token and merchant FNS number respectively.

Request:
```
curl -X 'POST' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${authentication_token}' \
  -H 'Merchant-Account: ${merchant identifier}' \
  'https://api.sandbox.joinforage.app/api/session_token/'
```
Response:
```
{"token": "sandbox_eyJhbGciOiJIUzI1NiI..."}
```
Merchant clients having received the token response from the merchant server can now communicate directly with the payments api for payment processing and capturing.
When the payments api responds with a 401 UNAUTHORIZED code from the use of the session token, the merchant client app should request a new session token from the merchant server.