Authentication with OAuth2

The Pismo platform supports OAuth2 authentication using stored credentials. Pismo's OAuth2 implementation follows the RFC 6749 specification, providing secure token-based authentication for API access. This guide explains how to obtain access tokens using the Client Credentials grant type.

Endpoint information

Token Endpoint

Sandbox: POST https://sandbox.pismolabs.io/passport/v2/oauth/token

Grant type

Pismo supports the Client Credentials grant type (client_credentials), which is designed for server-to-server authentication where the client application needs to access resources under its own identity.

Request parameters

Required parameters

Optional parameter

Scope attribute

Use the scope parameter to specify which groups of endpoints your token can access. You can pass:

• A single group: pismo-v1:accounts:rw
• Multiple groups separated by spaces: pismo-v1:accounts:rw pismo-v1:cards:rw pismo-v1:bankaccounts:rw

Pismo strongly recommends segregating tokens by using a reduced scope that includes only the specific permissions your application requires for each operation. This approach follows the principle of least privilege and provides several critical security benefits:

• Minimizes the potential damage from token compromise by limiting access to only necessary resources
• Reduces the attack surface by preventing unauthorized access to unrelated endpoints
• Enables better audit trails by clearly defining what each token can access
• Allows for more granular access control that can be easily monitored and revoked if suspicious activity is detected.

You can check all available scopes through Control Center. Refer to the Permission groups for OIDC guide for details.

UID Attribute

Use the uid parameter for account-specific token generation. If you intend to make calls on behalf of a specific account, you must also include the corresponding account identifier (uid). If you provide an account identifier, subsequent calls can only access resources that belong to that particular account.

You can find a complete list of the endpoints that you can use for requests in the API Reference. For a list of the endpoints that require the account identifier, refer to Endpoints that require an account-specific token.

To request an access token, use the following endpoint: Get Oauth access token

curl --request POST \ 

  --url https://sandbox.pismolabs.io/passport/v2/oauth/token \ 

  --header 'Content-Type: application/x-www-form-urlencoded' \ 

  --data grant_type=client_credentials \ 

  --data 'scope=pismo-v1:accounts:rw pismo-v1:cards:rw pismo-v1:bankaccounts:rw' \ 

  --data 'client_id=<your_client_id>' \ 

  --data 'client_secret=<your_client_secret>' \ 

  --data uid=12345 

Sample response

The following code shows an example of a response body for this request. It includes an access token (token), which you can use as an authorization header in future requests.

{ 

  "access_token": "<JWT_ACCESS_TOKEN>", 

  "token_type": "Bearer", 

  "expires_in": 3599, 

  "scope": "pismo-v1:accounts:rw pismo-v1:cards:rw pismo-v1:bankaccounts:rw" 

} 

Using the access token

Include the access token in the Authorization header of your API requests:

Authorization: Bearer <access_token>

📘

Access tokens expire after one hour (3600 seconds)

Your application should catch the error generated when this happens. It can then generate another JWT.

Renewing an expired token

Pismo does not support renewing access_token. The access token has a predefined lifetime. There is an exp field in the JWT that contains the date/time of expiration in Unix Epoch time. After the access token expires, the Pismo platform rejects additional requests. If you make a request using an expired token, the request returns Unauthorized. You should check for this message in your code and request a new access token when you receive it.

Best practices

• Secure storage—Store your client credentials securely and never expose them in client-side code.
• Token Caching—Cache tokens and reuse them until they expire to reduce unnecessary requests.
• Error Handling—Implement proper error handling for token expiration (401).
• Least Privilege—Request only the scopes your application actually needs.
• Keep JWT scope focused—Generate the JWT with the group for the intended API making the request.

Security considerations

• Monitor for unauthorized access attempts
• Rotate client credentials regularly