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 lidar diretamente com estas requisições e respostas HTTP. Esta página trata do formato das requisições e respostas 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 fluxo de login abaixo é o das aplicações de navegador web. As aplicações nativas (Android e iOS) tratam o callback de forma diferente, por isso são abordadas à parte em Callback de app nativo.

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).

Callback de app nativo: ponte de deep link

As aplicações nativas de Android e iOS também fazem login com o mesmo fluxo OAuth. Porém, como só é possível colocar um endereço web em callbackUrl, o modo de conexão é diferente.

O callbackUrl suportado pela documentação é um endereço web como https://.... Um esquema personalizado registrado pelo app, como myapp://, é rejeitado, portanto não pode ser usado diretamente como endereço de callback. Por isso, a aplicação nativa define o callbackUrl como uma página-ponte https hospedada no Web Hosting, e essa página repassa o ?exchangeToken=... contido no callback para o deep link do app (por exemplo, myapp://auth/callback?exchangeToken=...). O app realiza a troca de tokens (etapa 3 do fluxo de login acima, POST /spaces/{spaceId}/oauth/token) diretamente com esse exchangeToken.

• Pelo deep link passa apenas o exchangeToken de uso único. O accessToken e o refreshToken são obtidos pelo próprio app na troca, portanto não trafegam pelo deep link. A página-ponte também remove o exchangeToken do endereço depois de repassar o valor (mesmo princípio do callback no fluxo de login).
• Sempre que possível, use deep links verificados (Android App Links, iOS Universal Links). Um esquema personalizado não verificado pode ser interceptado por outro app instalado no dispositivo.
• O cliente OAuth do provedor (por exemplo, Google) é criado com o tipo Web application, mesmo para um app nativo. Isso porque o redirecionamento OAuth vai para auth.weegloo.com (um endereço web), e não para o app.

Como implantar a página-ponte é tratado em Web Hosting.

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).

{
  "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 não é um valor fixo. O horário exato de expiração vem em expiresAt na resposta, portanto use esse valor para determinar quando ele expira. É 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.