Для разработчиков

Обмен кода на токен

POST/oauth/token
Без авторизации

Второй шаг авторизации от имени сотрудника: код из адреса возврата меняется на токен этого сотрудника. Код действует 10 минут и обменивается один раз. Как получить код и проверить, чей токен пришёл, — в разделе Получение токена.

Тело передаётся в формате application/x-www-form-urlencoded, как требует OAuth 2.0. Серверное приложение подтверждает себя секретом клиента: полями client_id и client_secret или заголовком Authorization: Basic. Приложение без секрета передаёт client_id и code_verifier — проверочный код PKCE, из которого получен code_challenge ссылки авторизации.

Токен бессрочный: expires_in в ответе нет, и работает токен, пока сотрудник не отзовёт доступ. Если сотрудник уже авторизовал бота раньше, приходит его прежний токен. Чей это токен, показывает GETИнформация о токене.

Ошибки приходят в формате OAuth: invalid_grant — код истёк, уже использован, выдан для другого redirect_uri или не подходит code_verifier, а invalid_client — неверный client_id или client_secret. У обмена свой лимит: при его превышении метод отвечает 429 с кодом rate_limit в обычном формате ошибок API.

Тело запроса

application/x-www-form-urlencoded
grant_type
string
*
Тип запроса, всегда authorization_code
Возможные значения
Пример:authorization_code
code
string
*
Код авторизации из адреса возврата
Пример:ZmFrZV9hdXRoX2NvZGU
redirect_uri
string
*
Адрес возврата — тот же, что в ссылке авторизации
Пример:https://bot.example.com/oauth/callback
client_id
string
Идентификатор клиента с вкладки «OAuth» в карточке бота. Не нужен, если клиент передаёт его заголовком Authorization: Basic.
Пример:aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY
client_secret
string
Секрет клиента серверного приложения. Вместе с client_id его можно передать заголовком Authorization: Basic.
Пример:dGhpc19pc19ub3RfYV9yZWFsX3NlY3JldA
code_verifier
string
Проверочный код PKCE, из которого получен code_challenge ссылки авторизации. Обязателен для приложения без секрета.
Пример:dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Ответ

200OK
The request has succeeded.
access_token
string
*
Токен сотрудника. Передаётся в заголовке Authorization: Bearer при запросах от его имени.
Пример:pato_bm90X2FfcmVhbF90b2tlbg
token_type
string
*
Тип токена, всегда Bearer
Возможные значения
Пример:Bearer
refresh_token
string
*
Токен обновления. Токен сотрудника бессрочный, поэтому обновлять его не нужно.
Пример:cmVmcmVzaF9ub3RfcmVhbA
scope
string
*
Выданные права через пробел. Набор берётся из настроек бота.
Пример:chats:read messages:read tasks:read tasks:create
created_at
integer, (int64)
*
Время выдачи токена в формате Unix time, в секундах
Пример:1790242260
Обмен кода на токен
curl "https://api.pachca.com/api/shared/v1/oauth/token" \  -d 'grant_type=authorization_code' \  -d 'code=ZmFrZV9hdXRoX2NvZGU' \  -d 'redirect_uri=https://bot.example.com/oauth/callback' \  -d 'client_id=aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY' \  -d 'client_secret=dGhpc19pc19ub3RfYV9yZWFsX3NlY3JldA' \  -d 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
Ответ 200
{  "access_token": "pato_bm90X2FfcmVhbF90b2tlbg",  "token_type": "Bearer",  "refresh_token": "cmVmcmVzaF9ub3RfcmVhbA",  "scope": "chats:read messages:read tasks:read tasks:create",  "created_at": 1790242260}