OAuth 2.0 Client Credentials

Visão geral

A concessão Client Credentials foi feita para integrações servidor a servidor, sem ninguém presente: pipelines de CI, tarefas agendadas, serviços de backend e integrações de plataformas SaaS. Sua aplicação troca um par client_id / client_secret por um token de acesso Bearer de curta duração.

Quando usar OAuth ou chaves de API

1. Criar um cliente OAuth

Vá em Studio → API do desenvolvedor → Clientes OAuth 2.0 e clique em Criar cliente OAuth. Dê um nome descritivo e, se quiser, restrinja os escopos.

2. Obter um token de acesso

Envie uma requisição POST ao endpoint de token usando application/x-www-form-urlencoded (o padrão do RFC) ou application/json (por conveniência):

curl -X POST https://pollslive.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=plv_cid_…&client_secret=plv_cs_…&scope=polls:read polls:write"

curl -X POST https://pollslive.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "plv_cid_…",
    "client_secret": "plv_cs_…",
    "scope": "polls:read polls:write"
  }'

{
  "access_token": "plv_oauth_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "polls:read polls:write"
}

Os erros seguem o formato RFC 6749 §5.2. { "error": "invalid_client", "error_description": "…" }

3. Usar o token

Inclua o access_token como token Bearer em toda requisição à API, exatamente como uma chave de API:

curl https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer plv_oauth_…"

Sua aplicação deve armazenar o token em cache e pedir outro só quando expires_in estiver próximo (por exemplo, renovar quando faltarem menos de 5 minutos).

Validade e renovação do token

Os tokens valem 1 hora (expires_in: 3600). Não há token de atualização: basta pedir um novo com as credenciais do cliente quando o atual expirar. Como o fluxo é do lado do servidor, o segredo do cliente nunca sai do seu backend.

let token = null;
let expiresAt = 0;

async function getToken() {
  if (token && Date.now() < expiresAt - 5 * 60 * 1000) return token;

  const res = await fetch("https://pollslive.com/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
    }),
  });
  const data = await res.json();
  token = data.access_token;
  expiresAt = Date.now() + data.expires_in * 1000;
  return token;
}

Escopos

Escopos permitem limitar o que um cliente OAuth pode fazer. Se você não especificar nenhum ao criar o cliente, ele herda acesso total ao espaço de trabalho (equivalente a uma chave de API).

Veja a referência de escopos completa para a lista inteira.

Revogar um cliente

Revogar um cliente invalida imediatamente todos os tokens emitidos para ele. Requisições em andamento que usem um token falharão com 401 invalid_oauth_token.

Vá em Studio → API do desenvolvedor → Clientes OAuth 2.0 e clique em Revogar.