Перейти к содержанию
Sursa для разработчиков

POST/oauth/token

Выдать токен OAuth 2.0

oauth_token

Конечная точка выдачи токенов OAuth 2.0 (RFC 6749, раздел 3.2). grant_type: authorization_code обменивает одноразовый код на пару токенов и требует code_verifier (PKCE S256); refresh_token выдаёт новую пару по токену обновления и делает прежний токен обновления недействительным (ротация), а повторное использование недействительного отзывает всю цепочку; client_credentials выдаёт токен от имени организации — только для приложения confidential и без токена обновления. Клиент confidential аутентифицируется заголовком Authorization: Basic или полями client_id и client_secret; публичный клиент передаёт только client_id. Токен доступа действует 1 час, токен обновления — 90 дней. Ответы и ошибки соответствуют RFC 6749, раздел 5, с Cache-Control: no-store. Добавлено в 1.62.0.

Аутентификация

Учётные данные не нужны.

Тело запроса

application/x-www-form-urlencoded

Объект: OAuthTokenRequest

  • grant_typestringобязательно

    Допустимые значения: authorization_coderefresh_tokenclient_credentials

  • codestring

    Код авторизации (authorization_code).

  • redirect_uristring

    Тот же адрес возврата, что и в запросе авторизации (authorization_code).

  • code_verifierstring

    Исходное значение PKCE, от 43 до 128 символов (authorization_code).

  • refresh_tokenstring

    Токен обновления (refresh_token).

  • scopestring

    Области доступа через пробел, только для сужения (refresh_token, client_credentials).

  • client_idstring

    ID приложения, если секрет не передан в заголовке Authorization: Basic.

  • client_secretstring

    Секрет клиента приложения confidential, если он не передан в заголовке Authorization: Basic.

Ответы

200Токены выданы.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: OAuthTokenResponse

  • access_tokenstringобязательно

    Токен доступа (kbat_…) для заголовка Authorization: Bearer.

  • token_typestringобязательно

    Допустимые значения: Bearer

  • expires_inintegerобязательно

    Время жизни токена доступа в секундах.

  • refresh_tokenstring

    Токен обновления (kbrt_…); нет для client credentials.

  • scopestringобязательно

    Области доступа токена через пробел.

400Ошибка по RFC 6749, раздел 5.2.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: OAuthErrorResponse

401Неверные учётные данные клиента (`invalid_client`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: OAuthErrorResponse

Безопасные повторы

Передавайте заголовок Idempotency-Key (например, UUID) с каждым POST и PATCH. Повтор с тем же ключом в течение 24 часов возвращает сохранённый ответ, а не выполняет запрос снова.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← oauth · Справочник API