Перейти до вмісту
Sursa Developers

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

    Той самий URI перенаправлення, що й у запиті авторизації (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