Autenticação

Todas as APIs Zipdin utilizam autenticação via OAuth2 com tokens JWT (Bearer). Dependendo do tipo de integração, você utilizará um dos fluxos abaixo.

Fluxos Disponíveis

Client Credentials (M2M)
Authorization Code + PKCE

Para integrações server-to-server sem interação do usuário.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=SEU_CLIENT_ID
client_secret=SEU_CLIENT_SECRET
scope=api

Quando usar: Backends, jobs, pipelines de dados, integrações automatizadas.

Para aplicações frontend ou mobile onde o usuário faz login interativo.Passo 1 — Redirecionar para autorização:

GET /oauth/authorize?
  response_type=code
  &client_id=SEU_CLIENT_ID
  &redirect_uri=https://seuapp.com/callback
  &scope=api+profile
  &code_challenge=CHALLENGE_BASE64
  &code_challenge_method=S256

Passo 2 — Trocar code por token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=CODIGO_RECEBIDO
redirect_uri=https://seuapp.com/callback
client_id=SEU_CLIENT_ID
code_verifier=VERIFIER_ORIGINAL

Quando usar: Portais web, apps mobile, SPAs.

Estrutura do Token

O token JWT retornado contém as seguintes claims:

Claim	Descrição
`sub`	Identificador do usuário ou client
`iss`	Issuer (servidor de autenticação Zipdin)
`exp`	Timestamp de expiração (Unix)
`scope`	Escopos concedidos
`tenant`	Código da conveniada/parceiro

Usando o Token

Inclua o token no header Authorization de todas as requisições:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens expiram em 1 hora (3600 segundos). Implemente refresh automático para evitar interrupções na integração.

Refresh Token

Para fluxos com refresh_token, renove o acesso sem reautenticação:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=SEU_REFRESH_TOKEN
client_id=SEU_CLIENT_ID

Escopos Disponíveis

Escopo	Descrição	Acesso
`api`	Acesso geral às APIs	Leitura e escrita
`api:read`	Somente leitura	Consultas
`profile`	Dados do perfil do usuário	Login interativo
`admin`	Operações administrativas	Restrito

Erros de Autenticação

Para o catálogo completo de erros de todas as APIs, veja o guia de Tratamento de Erros. Abaixo, os erros específicos do fluxo de autenticação:

HTTP Status	Código	Descrição
401	`invalid_token`	Token expirado ou inválido
401	`missing_token`	Header Authorization ausente
403	`insufficient_scope`	Token não possui escopo necessário
429	`rate_limited`	Muitas tentativas de autenticação

Em homologação, você pode testar todo o fluxo de integração com dados fictícios antes de migrar para produção.

Começando

Conceitos

Autenticação

Autenticação

Fluxos Disponíveis

Estrutura do Token

Usando o Token

Refresh Token

Escopos Disponíveis

Erros de Autenticação

​Autenticação

​Fluxos Disponíveis

​Estrutura do Token

​Usando o Token

​Refresh Token

​Escopos Disponíveis

​Erros de Autenticação

Autenticação

Fluxos Disponíveis

Estrutura do Token

Usando o Token

Refresh Token

Escopos Disponíveis

Erros de Autenticação