> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paytsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens

> How Payt's access and refresh tokens work, and how to create, introspect, and use them.

To authorize API requests, you use an [access token](https://tools.ietf.org/html/rfc6749#section-1.4). If you use the Authorization Code flow, you also receive a [refresh token](https://tools.ietf.org/html/rfc6749#section-1.5) to obtain new access tokens.

Access tokens are the proof of authorization that our API requires. They must be added to the `Authorization` header of each request to the Payt API.

Each time you need a new access token, you must use the refresh token to request a new one. If your refresh token expires, the user needs to authorize your app again. In order to prevent this, a new refresh token is returned each time a new access token is created. This way your app remains authorized as long as it is used frequently.

| Token         | Expiry  | Notes                                                                                       |
| ------------- | ------- | ------------------------------------------------------------------------------------------- |
| Access token  | 2 hours | Must be refreshed using the refresh token after expiry.                                     |
| Refresh token | 90 days | Rotated on every use; a new refresh token is returned each time you create an access token. |

<Note>
  As long as your app requests a new access token at least once every 90 days, the refresh token never expires in practice.
</Note>

## Create tokens

A new set of tokens can be created by sending a request to the token endpoint (`/oauth/token`) using the last received refresh token. The very first refresh token is received during the [confirmation step](/authentication/authorization#confirm-the-authorization) of the authorization process.

**Request:**

<CodeGroup>
  ```http Request theme={null}
  POST https://api.paytsoftware.com/oauth/token
  Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0

  {
    "grant_type": "refresh_token",
    "refresh_token": "PKWuvzHNj3ALI0G7QNBGjBI1-q3aMLZBqgXdaaumk18"
  }
  ```

  ```bash cURL theme={null}
  curl --header 'Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0' \
  --form 'grant_type=refresh_token' \
  --form 'refresh_token=PKWuvzHNj3ALI0G7QNBGjBI1-q3aMLZBqgXdaaumk18' \
  --request POST https://api.paytsoftware.com/oauth/token
  ```
</CodeGroup>

| Header          | Presence | Definition                                   |
| --------------- | -------- | -------------------------------------------- |
| `Authorization` | required | [Basic](/authentication/basic-authorization) |

| Parameter       | Presence | Definition                               |
| --------------- | -------- | ---------------------------------------- |
| `grant_type`    | required | Must be: `refresh_token`.                |
| `refresh_token` | required | Must be the last refresh token received. |

**Response:**

```json theme={null}
{
  "access_token": "2GyChYPFxhYOis/uiLoVkA==",
  "created_at": 1577836800,
  "expires_in": 7200,
  "refresh_token": "PKWuvzHNj3ALI0G7QNBGjBI1-q3aMLZBqgXdaaumk18",
  "scope": "invoices:read debtors:read",
  "token_type": "Bearer"
}
```

| Key             | Value                                                         |
| --------------- | ------------------------------------------------------------- |
| `access_token`  | The token that can be used to authenticate API requests.      |
| `created_at`    | The UNIX time at which the token was created.                 |
| `expires_in`    | The number of seconds the access token is valid.              |
| `refresh_token` | The new refresh token, must be used to create the next token. |
| `scope`         | List of granted permissions.                                  |
| `token_type`    | Will always be `Bearer`.                                      |

## Introspect a token

Besides the scopes that are granted, you might want to know for which company and which administrations of this company the authorization was granted. This information can be retrieved by sending an active token (either an access token or refresh token) to the [introspect](https://tools.ietf.org/html/rfc7662) endpoint.

**[Request](https://tools.ietf.org/html/rfc7662#section-2.1)**

<CodeGroup>
  ```http Request theme={null}
  POST https://api.paytsoftware.com/oauth/introspect
  Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0

  {
    "token": "IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8"
  }
  ```

  ```bash cURL theme={null}
  curl --header 'Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0' \
  --form token=IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8 \
  --request POST https://api.paytsoftware.com/oauth/introspect
  ```
</CodeGroup>

**[Response](https://tools.ietf.org/html/rfc7662#section-2.2)**

```json theme={null}
{
  "active": true,
  "administrations": [
    {
      "id": "123",
      "name": "Administration Name"
    },
    {
      "id": "321",
      "name": "Administration Two Name"
    }
  ],
  "client_id": "q-QynnbDDXVFJCHUPg58EWHH2n5kCWaWYeJ5lVQNI7A",
  "company": {
    "id": "123",
    "name": "Company Name"
  },
  "exp": 1577844000,
  "iat": 1577836800,
  "scope": "invoices:read debtors:read",
  "token_type": "Bearer"
}
```

| Key               | Value                                                                        |
| ----------------- | ---------------------------------------------------------------------------- |
| `active`          | Whether the access token (not the refresh token) is still valid.             |
| `administrations` | List of administration ids and names the token is granted access to.         |
| `client_id`       | The client\_id of the application.                                           |
| `company`         | The id and name of the company the token is granted access to.               |
| `exp`             | The UNIX time at which the access token (not the refresh token) will expire. |
| `iat`             | The UNIX time at which the token was created.                                |
| `scope`           | List of granted permissions.                                                 |
| `token_type`      | Will always be `Bearer`.                                                     |

If the given token has expired, does not belong to your client or does not exist, the following response will be returned:

**Response:**

```json theme={null}
{
  "active": false
}
```

## Use an access token / static API token

To query the Payt API an active access token must be added to the `Authorization` header, preceded by `Bearer`:

<CodeGroup>
  ```http Request theme={null}
  GET https://api.paytsoftware.com/v1/invoices?administration_id=123
  Authorization: Bearer IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8
  ```

  ```bash cURL theme={null}
  curl https://api.paytsoftware.com/v1/invoices?administration_id=123 \
  --header 'Authorization: Bearer IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8'
  ```
</CodeGroup>