Auth API

A Auth API é o fluxo OAuth que autentica um ServiceUser (o assinante comum do produto operado por um Space) por meio de login social. Ao fazer login com um provedor conectado à configuração de ServiceLogin (por exemplo, Google), esta API emite um accessToken e um refreshToken. O accessToken emitido é um token Bearer usado apenas em chamadas ACMA e ACDA, e não pode ser usado em CMA e CDA. Não há tokens que cruzem o limite de identidade.

A URL base é https://auth.weegloo.com/v1, e todos os caminhos ficam sob /spaces/{spaceId}/.... Todos os corpos de requisição e resposta são JSON. Em aplicações de navegador, recomenda-se usar o SDK oficial weegloo-service-user em vez de manipular este protocolo diretamente. Esta página trata do protocolo HTTP que esse SDK chama internamente. Consulte-a ao implementar o fluxo diretamente em ambientes em que o SDK não pode ser usado (servidor, nativo, scripts).

Fluxo de login

O login ocorre em quatro etapas.

1. Direcione o navegador para a URL de entrada do login (/spaces/{spaceId}/login/oauth2/{provider}). Essa URL inicia a cadeia de redirecionamentos que leva à tela de login do provedor (Google).
2. Concluído o login, o Weegloo devolve o navegador à callbackUrl configurada no ServiceLogin e anexa ?exchangeToken=<token de uso único> ao endereço.
3. A página de callback lê o exchangeToken do endereço e o envia para o endpoint de troca de tokens (POST /spaces/{spaceId}/oauth/token), recebendo na resposta o accessToken e o refreshToken.
4. Depois disso, use o accessToken como token Bearer para chamar a ACMA e a ACDA. Renove-o com o refreshToken antes da expiração (expiresAt) e descarte os tokens ao fazer logout.

O exchangeToken é de uso único. Logo após processar o callback, remova-o imediatamente da barra de endereço para evitar exposição e reutilização (se você usar o SDK, isso é tratado automaticamente).

Modelo de tokens

A troca e a renovação de tokens devolvem uma resposta de token com o mesmo formato. As strings de token e os horários contidos na resposta são os valores de exemplo abaixo; na prática são strings secretas opacas (como o fluxo passa pelo login do provedor, não é possível reproduzir os valores reais aqui). A estrutura e os campos são fatos verificados no código do servidor.

{
  "accessToken": "QY3xK9pR2mLs7Vc0Zt8Nf4Wd1Bj6Hg5Ua2Ee9Ck3PoZt8Nf4Wd",
  "tokenType": "Bearer",
  "scope": ["APP"],
  "createdAt": "2026-06-18T05:00:00.000Z",
  "expiresAt": "2026-06-19T05:00:00.000Z",
  "refreshToken": "Rf7Hn2Qw9Zx4Tp1Lk6Vc3Bm8Yd5Gs0Ae2Uj7Co4NeLk6Vc3Bm",
  "refreshExpiresAt": "2026-06-21T05:00:00.000Z"
}

A vida útil dos três tokens é a seguinte.

• O exchangeToken é de uso único e tem vida curta. Deve ser trocado imediatamente após o callback. Ele não vem na resposta da troca; é entregue no endereço na etapa 2 do fluxo de login.
• A vida útil do accessToken segue a configuração do servidor, e o horário exato de expiração vem em expiresAt na resposta. É exclusivo de ACMA e ACDA.
• O refreshToken é válido por três dias após a emissão (refreshExpiresAt). Ao chamar a renovação, um novo par de accessToken e refreshToken é emitido e o par anterior é descartado (rotação, rotation). A cada renovação, o refreshToken imediatamente anterior deixa de ser utilizável.

API

A URL base dos quatro endpoints abaixo é sempre https://auth.weegloo.com/v1. Eles são tratados na ordem: entrada do login (GET), troca de tokens (POST), renovação de tokens (POST) e logout (DELETE).

Documentos relacionados

• Login de ServiceUser (conceito): como configurar o ServiceLogin no estúdio de conteúdo.
• ACMA: API para manipular o conteúdo dos membros com o token emitido.
• ACDA: API de leitura entregue aos membros.