# Postman and Insomnia collections

> A ready-made collection of requests to all public API methods for manual work.

The collection contains all methods available to an integration key, grouped into the same sections as the [list of key routes](/en/reference/permissions/). Authorization is set to `Bearer {{access_token}}`, and the server address is placed in the `baseUrl` variable. For asynchronous methods the `Billz-Response-Channel: HTTP` header is already set. Optional headers with no default value, such as `accept-language`, are disabled: enable them and set a value if they are needed.

File: [billz-api.postman\_collection.json](/collections/billz-api.postman_collection.json) (Postman Collection v2.1 format, readable by both Postman and Insomnia; the request names in the collection are in Russian).

## Variables

| Variable        | Value                                                                     |
| --------------- | ------------------------------------------------------------------------- |
| `baseUrl`       | `https://api-admin.billz.ai`                                              |
| `secret_token`  | the integration key — the only variable that has to be filled in manually |
| `access_token`  | filled in automatically by the **Get access token** request               |
| `refresh_token` | filled in automatically, used by the **Refresh access token** request     |

## How to get a token

1. Fill in the `secret_token` variable with the integration key.
2. Run **Get access token** (`POST /v1/auth/login`) in the “Authentication” section. The request script saves `access_token` and `refresh_token` from the response into the collection variables.
3. From then on, all requests in the collection are authorized. When `access_token` expires, run **Refresh access token** (`POST /v2/auth/refresh`): the request body takes `refresh_token` from the variable, and the script updates both variables.

While `access_token` is empty, requests are sent without the `Authorization` header, and the API responds with `401 UNAUTHORIZED`.

## Postman

1. **Import → Upload Files**, select the collection file.
2. Open the collection → the **Variables** tab → fill in the *Current value* of the `secret_token` variable. `baseUrl` can be changed there as well if needed.
3. Run **Get access token** — the tokens appear in *Current value*.

## Insomnia

1. **Import → From File**, select the same file. Insomnia recognizes the Postman format, including request scripts.
2. The collection variables go into the collection’s base environment (**Manage Environments**); `secret_token` is set there.
3. Run **Get access token** — the script writes the tokens into the same environment.

## Updates

The collection is generated from the OpenAPI specification and is not edited by hand: when the specification changes, the collection is rebuilt and updated in the repository together with it.