Do código ao token
Como trocar o código temporário (orb_ac_) por um access token, usar o Bearer, renovar com refresh e revogar tokens.
Esta é a página central da troca OAuth. Depois que o usuário aprovou o consentimento, você recebe um código temporário e o troca por um access token para chamar a API em nome dele. Aqui você faz tudo isso: recebe o code, troca por token, usa o Bearer, renova com refresh e revoga quando preciso.
Antes de começar
A troca de token acontece servidor-a-servidor (POST /api/oauth/token). Se o seu app for public, você precisa do code_verifier do PKCE gerado antes do /authorize — veja PKCE em detalhe. Se for confidential, você também envia o client_secret.
1. Receber o código
Quando o usuário aprova o consentimento, o navegador dele volta para a redirect_uri que você registrou, com dois parâmetros na query:
GET https://seu-app.com/callback?code=orb_ac_XXXXXXXXXXXX&state=SEU_STATESe o usuário negou o consentimento, você recebe um erro em vez do código:
GET https://seu-app.com/callback?error=access_denied&state=SEU_STATEValide o state
Compare o state recebido com o valor opaco que você gerou antes de redirecionar para o /authorize. Se não bater, descarte a requisição — é a sua proteção anti-CSRF.
Trate o access_denied
Se vier error=access_denied, o usuário recusou. Não há token; encerre o fluxo com uma mensagem amigável.
Use o code imediatamente
O code (orb_ac_...) é de uso único e expira em 60 segundos. Troque-o por token na hora — não guarde para depois.
2. Trocar o código por token
Faça um POST para o endpoint de token, com o corpo em application/x-www-form-urlencoded.
curl -X POST https://api.orbitsender.com/api/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=cli_abc123" \
-d "code=orb_ac_XXXXXXXXXXXX" \
-d "redirect_uri=https://seu-app.com/callback" \
-d "code_verifier=SEU_CODE_VERIFIER"Rate limit
O POST /api/oauth/token é limitado a 30 requisições por minuto por client_id
(mesmo bucket para a troca do code e para o refresh). Ao estourar, você recebe
429 com o header Retry-After: 60 e o corpo { "success": false, "error": "rate_limited" }.
Faça backoff antes de retentar — especialmente em loops de refresh.
App confidential
Se o seu app for do tipo confidential, adicione também o client_secret:
-d "client_secret=cs_live_XXXXXXXXXXXX"Apps public não têm secret — a segurança vem do PKCE (code_verifier).
Resposta de sucesso (200):
{
"success": true,
"access_token": "orb_at_XXXXXXXXXXXX",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "orb_rt_XXXXXXXXXXXX",
"scope": "statistics:read campaigns:read"
}| Campo | Significado |
|---|---|
access_token | Token orb_at_ para chamar a API. Validade ~1h (expires_in). |
token_type | Sempre Bearer. |
expires_in | Segundos até o access token expirar (3600 = 1h). |
refresh_token | Token orb_rt_ para obter um novo access token. Rotativo (veja abaixo). |
scope | Scopes efetivamente concedidos, separados por espaço. |
Guardamos só o hash
O OrbitSender armazena apenas o SHA-256 dos tokens. Guarde o access_token e o refresh_token com segurança do seu lado — eles não podem ser recuperados depois.
3. Usar o access token
Chame qualquer endpoint autorizado passando o token no header Authorization: Bearer. Exemplo com as estatísticas de parceiro:
curl https://api.orbitsender.com/api/external/partner/statistics?days=30 \
-H "Authorization: Bearer orb_at_XXXXXXXXXXXX"Os scopes concedidos determinam o que você pode acessar, e a máscara de parceiro remove PII das respostas. Veja tudo em Chamar a API em nome do usuário.
4. Renovar com refresh token
Quando o access_token expira (~1h), troque o refresh_token por um par novo:
curl -X POST https://api.orbitsender.com/api/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=cli_abc123" \
-d "refresh_token=orb_rt_XXXXXXXXXXXX"App confidential: adicione também
-d "client_secret=cs_live_XXXXXXXXXXXX".
A resposta tem o mesmo formato do passo 2, com um novo access_token e um novo refresh_token.
Rotação e detecção de reuse
O refresh_token é rotativo: cada uso invalida o anterior. Sempre substitua o refresh antigo pelo novo que veio na resposta.
Se você reapresentar um refresh já usado, o OrbitSender detecta o reuse e revoga a família inteira de tokens (todos os access e refresh derivados daquele consentimento). Nunca reutilize um refresh antigo nem faça duas chamadas de refresh em paralelo com o mesmo token.
5. Revogar um token
Para invalidar um token explicitamente (logout, desvínculo etc.), use o endpoint de revogação (RFC 7009):
curl -X POST https://api.orbitsender.com/api/oauth/revoke \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=orb_rt_XXXXXXXXXXXX"Sempre 200
O /api/oauth/revoke responde sempre 200, mesmo se o token já era inválido ou desconhecido. Não trate a resposta como confirmação de que o token existia.
O usuário também pode revogar o acesso do seu app a qualquer momento pelo painel, em Apps Conectados (dentro do app OrbitSender). Nesse caso seus tokens deixam de funcionar. Trate erros de token expirado/revogado com elegância — veja Gerenciar vínculos, revogação e erros.