--- updatedAt: 2026-07-15T20:21:36.000Z --- Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # 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** | Parameter | Type | Description | | :-------------- | :----- | :----------------------------------------------------------------------------- | | `grant_type` | string | Must be set to `client_credentials` | | `client_id` | string | Your application's client identifier (server key) | | `client_secret` | string | Your application's client secret (server secret) | | `scope` | string | Space-separated list of permission groups that define the token's access scope | **Optional parameter** | Parameter | Type | Description | | :-------- | :----- | :-------------------------------------------------------------------------------- | | `uid` | string | Account ID for account-specific token generation (required for certain endpoints) | ### 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 Control Center Permission groups 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` ```json curl --request POST \ --url https://sandbox.pismolabs.io/passport/v2/oauth/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode grant_type=client_credentials \ --data-urlencode 'scope=pismo-v1:accounts:rw pismo-v1:cards:rw pismo-v1:bankaccounts:rw' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ --data-urlencode 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. ```json { "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 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. You can use the JWT Debugger website to view the fields in a JWT. Holding the mouse pointer over the decoded `exp` value displays it as a human-readable date/time. If you need to access the field values in your code, refer to Parsing the JWT. ## 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 # Third-party authentication with OAuth2 The Pismo platform enables you to give a third-party access to a restricted set of Pismo endpoints that they can use within your organization. This would enable them to authenticate with the Pismo platform, but they would only get access to the specific endpoints that you want them to access. For more information, refer to the Third-party authentication guide.