Autenticação

A API usa tokens Bearer para identificar o usuário e aplicar as permissões da conta, do workspace e do departamento selecionados.

Existem duas formas de obter acesso. Dentro deste portal, a autorização pode ser preenchida automaticamente. Em uma integração própria, sua aplicação deve realizar o login e renovar a sessão.

📘
Nunca inclua tokens, senhas ou o segredo do webhook em código público, exemplos compartilhados ou aplicações executadas no navegador.

Autenticar uma integração

Envie as credenciais do usuário para POST /auth/login.

curl --request POST \
  --url https://api.seudominio.com/auth/login \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[email protected]",
    "password": "sua_senha"
  }'

Uma autenticação bem sucedida retorna um access token curto e um refresh token opaco.

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "a1b2c3d4...",
  "tokenType": "Bearer",
  "userId": "usr_a1b2c3",
  "email": "[email protected]",
  "name": "Empresa Exemplo",
  "role": "user",
  "customerType": "company"
}

O access token é um JWT com validade curta. O refresh token é um valor aleatório e opaco associado a uma sessão. Ele não é um JWT.

Autorizar requests

Envie o access token no cabeçalho Authorization de toda rota protegida.

curl --request GET \
  --url https://api.seudominio.com/user/me \
  --header "Authorization: Bearer SEU_ACCESS_TOKEN"

O prefixo Bearer é obrigatório e deve ser separado do token por um espaço.

Para operações vinculadas a um ambiente ou departamento, envie também o contexto solicitado pelo endpoint.

Authorization: Bearer SEU_ACCESS_TOKEN
X-Workspace-ID: SEU_WORKSPACE_ID
X-Department-ID: SEU_DEPARTMENT_ID

📘
O token identifica o usuário. Os cabeçalhos de contexto não ampliam suas permissões. A API valida se o usuário pode acessar o workspace e o departamento informados.

Renovar a sessão

Quando o access token expirar, envie o refresh token para POST /auth/refresh.

curl --request POST \
  --url https://api.seudominio.com/auth/refresh \
  --header "Content-Type: application/json" \
  --data '{
    "refreshToken": "SEU_REFRESH_TOKEN"
  }'

A resposta contém um novo par de tokens. Substitua imediatamente os dois valores armazenados. O refresh token anterior deixa de ser válido após a rotação.

sequenceDiagram
  participant Aplicacao
  participant API
  Aplicacao->>API: POST /auth/login
  API-->>Aplicacao: access token e refresh token
  Aplicacao->>API: Request com Bearer token
  API-->>Aplicacao: Resposta protegida
  Aplicacao->>API: POST /auth/refresh
  API-->>Aplicacao: Novo par de tokens

Tratar erros de acesso

Status	Significado	Ação recomendada
`401`	Token ausente, inválido, expirado ou revogado	Renove a sessão uma vez. Se a renovação falhar, solicite um novo login.
`403`	Usuário autenticado sem permissão para a operação	Não repita automaticamente. Verifique a função do usuário e o contexto informado.
`429`	Limite de tentativas ou requests atingido	Respeite o tempo de espera informado antes de tentar novamente.

Não use uma resposta 403 como gatilho para renovar tokens. Ela representa uma decisão de permissão, não uma sessão expirada.

Armazenamento seguro

Aplicações web devem manter tokens fora do alcance do JavaScript sempre que possível, usando cookies HttpOnly, Secure e uma política SameSite adequada à arquitetura.

Aplicações móveis e serviços devem usar o armazenamento seguro oferecido pelo sistema operacional ou pelo ambiente de execução.

Use sempre HTTPS. Ao encerrar uma sessão, descarte os tokens armazenados e chame POST /auth/logout. Para encerrar todas as sessões do usuário, use POST /auth/logout-all.