Quick Start: Login com a Cativa em 5 minutos

Em 5 minutos você vai ter um botão Entrar com Cativa funcionando no seu app. Esse fluxo é ideal quando você quer que o usuário final autentique com a conta dele da comunidade, sem criar senha nova no seu produto. Se você só precisa de acesso server-to-server (jobs, sincronizações, sem usuário no meio), use Primeira chamada de API, que é mais simples.

O que é OAuth 2.0 com PKCE

OAuth 2.0 é o protocolo padrão para um app pedir acesso em nome de um usuário sem nunca ver a senha dele. O usuário faz login na Cativa, a Cativa devolve um código temporário para o seu app, e o seu app troca esse código por um access_token. PKCE (Proof Key for Code Exchange) é uma camada de segurança sobre o OAuth. Antes de mandar o usuário para o login, você gera um segredo aleatório (o code_verifier) e envia apenas o hash dele (o code_challenge). Na hora de trocar o código pelo token, você revela o code_verifier original. A Cativa recomputa o hash e confere. Isso impede que alguém que intercepte o código o use, porque não tem o code_verifier.

Os endpoints SSO da Cativa seguem o padrão OIDC e são organizados por slug do tenant ({customerName}). Esse slug é o subdomínio público da comunidade. Confirme com o admin do tenant qual valor usar. A base dos endpoints é https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}.

O fluxo em uma olhada

Seu app gera code_verifier + code_challenge (PKCE)
Redireciona o usuário para /authorize
Usuário faz login na Cativa e consente
Cativa redireciona de volta com ?code=...
Seu backend troca o code por access_token no /token
Seu app chama /userinfo e obtém o perfil

Crie um OAuth App no Console

Vá em app.cativa.digital/admin/developers, aba OAuth Apps, clique em Criar app.Anote o client_id e o client_secret retornados. O secret aparece uma única vez, guarde com cuidado num cofre de credenciais.

Configure o redirect URI

No mesmo modal, adicione seu redirect URI (ex: https://meuapp.com/callback, ou http://localhost:3000/callback para desenvolvimento). A redirect_uri que você enviar depois precisa bater exatamente com uma das cadastradas aqui.

Redirecione o usuário para o /authorize

No frontend, gere um code_verifier e code_challenge (PKCE), guarde o verifier na sessão e redirecione para o endpoint /authorize do tenant:

const verifier = generateRandomString(64);
const challenge = await sha256(verifier);
sessionStorage.setItem('pkce_verifier', verifier);

const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://meuapp.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
  code_challenge: challenge,
  code_challenge_method: 'S256',
  state: crypto.randomUUID()
});

// Substitua {customerName} pelo slug do tenant
window.location.href = `https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/authorize?${params}`;

Guarde também o state na sessão e confira no callback. Ele protege contra CSRF: se o state que voltar não for o que você enviou, descarte o request.

Troque o code por um access_token no callback

Depois que o usuário consente, a Cativa redireciona para sua URL com ?code=...&state=.... No backend, faça POST no endpoint /token do mesmo tenant, com o body em application/x-www-form-urlencoded:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=CODE_DO_CALLBACK" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://meuapp.com/callback" \
  -d "code_verifier=VERIFIER_DA_SESSION"

const res = await fetch(`https://apis.cativalab.digital/tenant/api/v2/sso/${customerName}/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: req.query.code,
    client_id: process.env.CATIVA_CLIENT_ID,
    client_secret: process.env.CATIVA_CLIENT_SECRET,
    redirect_uri: 'https://meuapp.com/callback',
    code_verifier: req.session.pkceVerifier
  })
});
const { access_token, id_token } = await res.json();

import os
import requests

res = requests.post(
    f'https://apis.cativalab.digital/tenant/api/v2/sso/{customer_name}/token',
    data={
        'grant_type': 'authorization_code',
        'code': code,
        'client_id': os.environ['CATIVA_CLIENT_ID'],
        'client_secret': os.environ['CATIVA_CLIENT_SECRET'],
        'redirect_uri': 'https://meuapp.com/callback',
        'code_verifier': session['pkce_verifier']
    }
)
tokens = res.json()

A resposta segue o padrão OIDC:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def50200a1b2c3..."
}

O code é single-use e expira em poucos minutos. Faça a troca imediatamente no callback. Se você receber invalid_grant, provavelmente o code expirou ou já foi usado (ex: usuário deu reload na tela de callback).

Pegue informações do usuário

Use o access_token no endpoint userinfo:

curl https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Resposta:

{
  "sub": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "picture": "https://cdn.cativa.digital/avatars/..."
}

O sub é o ID estável do usuário na Cativa. Use-o como chave para associar o usuário à sessão do seu app.

O documento de descoberta OIDC do tenant fica em https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/.well-known/openid-configuration e lista todos os endpoints (authorize, token, userinfo, jwks) e algoritmos suportados (S256 para PKCE, ES256 para assinatura do id_token). O JWKS público fica em https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/jwks. Bibliotecas como jose (Node) ou PyJWT (Python) leem o discovery e validam o id_token automaticamente.

Este quickstart mostra o caminho feliz. Antes de ir para produção, valide a assinatura do id_token via JWKS e trate os erros de OAuth (invalid_grant, invalid_client, falha de PKCE). O passo a passo completo, com SPA, backend e mobile, está no guia Implementar Login com a Cativa.

Próximos passos

Guia completo de SSO

SPA, backend e mobile, validação de id_token via JWKS, renovação de token e erros comuns.

Tenants e Customers

Entenda o conceito de customerName no fluxo OIDC e quando o tenant aparece nas integrações.

Primeira chamada de API

Para integrações server-to-server, use API Key direto em vez de OAuth.

Badges como permissão

Como o sub do usuário se conecta ao que ele pode acessar na comunidade.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Quick Start: Login com a Cativa em 5 minutos

O que é OAuth 2.0 com PKCE

O fluxo em uma olhada

Próximos passos

Guia completo de SSO

Tenants e Customers

Primeira chamada de API

Badges como permissão

​O que é OAuth 2.0 com PKCE

​O fluxo em uma olhada

​Próximos passos

Guia completo de SSO

Tenants e Customers

Primeira chamada de API

Badges como permissão

O que é OAuth 2.0 com PKCE

O fluxo em uma olhada

Próximos passos