Ir al contenido
Sursa Developers

POST/oauth/token

Emitir un token OAuth 2.0

oauth_token

El endpoint de token de OAuth 2.0 (RFC 6749, sección 3.2). grant_type: authorization_code canjea un código de un solo uso por un par de tokens y requiere code_verifier (PKCE S256); refresh_token emite un par nuevo a cambio de un token de actualización e invalida el token de actualización anterior (rotación), y reutilizar uno invalidado revoca toda la cadena; client_credentials emite un token en nombre de la organización, solo para una aplicación confidential y sin token de actualización. Un cliente confidential se autentica con el encabezado Authorization: Basic o con los campos client_id y client_secret; un cliente público solo envía client_id. Un token de acceso es válido durante 1 hora; un token de actualización, durante 90 días. Las respuestas y los errores siguen la RFC 6749, sección 5, con Cache-Control: no-store. Se añadió en 1.62.0.

Autenticación

No se necesitan credenciales.

Cuerpo de la solicitud

application/x-www-form-urlencoded

Objeto: OAuthTokenRequest

  • grant_typestringobligatorio

    Valores permitidos: authorization_coderefresh_tokenclient_credentials

  • codestring

    Código de autorización (authorization_code).

  • redirect_uristring

    La misma URI de redirección que en la solicitud de autorización (authorization_code).

  • code_verifierstring

    El valor PKCE original, de 43 a 128 caracteres (authorization_code).

  • refresh_tokenstring

    Token de actualización (refresh_token).

  • scopestring

    Ámbitos separados por espacios, solo para restringir (refresh_token, client_credentials).

  • client_idstring

    ID de la aplicación, cuando el secreto no se envía en el encabezado Authorization: Basic.

  • client_secretstring

    Secreto de cliente de una aplicación confidential, cuando no se envía en el encabezado Authorization: Basic.

Respuestas

200Se emitieron los tokens.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: OAuthTokenResponse

  • access_tokenstringobligatorio

    Token de acceso (kbat_…) para el encabezado Authorization: Bearer.

  • token_typestringobligatorio

    Valores permitidos: Bearer

  • expires_inintegerobligatorio

    Duración del token de acceso en segundos.

  • refresh_tokenstring

    Token de actualización (kbrt_…); no aparece con client credentials.

  • scopestringobligatorio

    Ámbitos del token separados por espacios.

400Error según la definición de la RFC 6749, sección 5.2.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: OAuthErrorResponse

401Credenciales de cliente no válidas (`invalid_client`).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: OAuthErrorResponse

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← oauth · Referencia de la API