# 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` | 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 [Permission groups for OIDC](https://developers.pismo.io/pismo-docs/docs/cc-api-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](https://developers.pismo.io/pismo-docs/reference/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=<your_client_id>' \ 

  --data-urlencode 'client_secret=<your_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": "<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 <your_bearer_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](https://www.unixtutorial.org/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