Pular para o conteúdo
Sursa Developers

POST/oauth/token

Emitir um token OAuth 2.0

oauth_token

O endpoint de token do OAuth 2.0 (RFC 6749, seção 3.2). grant_type: authorization_code troca um código de uso único por um par de tokens e exige code_verifier (PKCE S256); refresh_token emite um novo par em troca de um token de atualização e invalida o token de atualização anterior (rotação), e reutilizar um token invalidado revoga a cadeia inteira; client_credentials emite um token em nome da organização, só para um app confidential, sem token de atualização. Um cliente confidential se autentica com o cabeçalho Authorization: Basic ou com os campos client_id e client_secret; um cliente público envia só client_id. Um token de acesso vale por 1 hora, e um token de atualização, por 90 dias. As respostas e os erros seguem a RFC 6749, seção 5, com Cache-Control: no-store. Adicionado na versão 1.62.0.

Autenticação

Não são necessárias credenciais.

Corpo da requisição

application/x-www-form-urlencoded

Objeto: OAuthTokenRequest

  • grant_typestringobrigatório

    Valores permitidos: authorization_coderefresh_tokenclient_credentials

  • codestring

    Código de autorização (authorization_code).

  • redirect_uristring

    O mesmo URI de redirecionamento da requisição de autorização (authorization_code).

  • code_verifierstring

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

  • refresh_tokenstring

    Token de atualização (refresh_token).

  • scopestring

    Escopos separados por espaço, só para restringir (refresh_token, client_credentials).

  • client_idstring

    ID do app, quando o segredo não é passado no cabeçalho Authorization: Basic.

  • client_secretstring

    Segredo do cliente de um app confidential, quando não é passado no cabeçalho Authorization: Basic.

Respostas

200Os tokens foram emitidos.

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: OAuthTokenResponse

  • access_tokenstringobrigatório

    Token de acesso (kbat_…) para o cabeçalho Authorization: Bearer.

  • token_typestringobrigatório

    Valores permitidos: Bearer

  • expires_inintegerobrigatório

    Tempo de vida do token de acesso em segundos.

  • refresh_tokenstring

    Token de atualização (kbrt_…); ausente em client credentials.

  • scopestringobrigatório

    Escopos do token separados por espaço.

400Erro conforme definido na RFC 6749, seção 5.2.

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: OAuthErrorResponse

401Credenciais do cliente inválidas (`invalid_client`).

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: OAuthErrorResponse

Novas tentativas seguras

Envie um cabeçalho Idempotency-Key (por exemplo, um UUID) em cada POST e PATCH. Uma nova tentativa com a mesma chave em até 24 horas retorna a resposta salva, em vez de executar a requisição de novo.

Limites de taxa

As respostas trazem os cabeçalhos RateLimit e RateLimit-Policy e os anteriores X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta 429 traz Retry-After em segundos: aguarde e tente de novo.

← oauth · Referência da API