Autenticação

Toda chamada à API (menos o login dos aplicativos) leva um token no cabeçalho Authorization. Existem dois tipos de cliente, e os dois usam o mesmo formato de token:

Cliente	Como obtém o token	O que pode fazer	Validade
Integração (sistema de terceiros da prefeitura)	Criado pelo administrador da prefeitura no painel	O que os escopos e o recorte da integração permitem	Não expira; vale até ser trocado ou revogado
Aplicativo do GedFlow (celular, tablet)	Login com e-mail e senha de um usuário da prefeitura	O mesmo que esse usuário pode fazer no painel	30 dias por aparelho

O cabeçalho#

GET /api/v1/me HTTP/1.1
Host: gedflow.com.br
Authorization: Bearer 12|q8Zr3VxK0bN7yTfP2mWcL5sHdA9uJ4eGiR6oYkQ1
Accept: application/json

Envie o token inteiro, incluindo o número e a barra vertical do começo. Sempre por HTTPS.

Token de integração#

O token da integração é emitido pelo administrador da prefeitura em Integrações, e aparece uma única vez na tela, logo depois de salvar. Ninguém consegue vê-lo de novo, nem a prefeitura nem a equipe do GedFlow: se perder, é preciso gerar outro.

• Cada integração tem um token válido por vez.
• Ele carrega os escopos da integração. Se o administrador mudar os escopos, o mesmo token passa a valer com os escopos novos, sem troca.
• O token pertence a um usuário técnico da integração, que não entra nos painéis e não faz login pela API.

Como a prefeitura cria e administra a integração: Integrações com outros sistemas.

Trocar o token (rotação)#

Quando o administrador clica em Gerar novo token, o novo token aparece uma vez e o anterior deixa de valer imediatamente. Não há período de convivência entre os dois.

Para trocar sem susto:

1. Combine um horário com o administrador.
2. Deixe o seu sistema pronto para ler o token de uma variável de ambiente ou cofre de segredos, sem precisar de nova versão do código.
3. O administrador gera o novo token e repassa por canal seguro.
4. Atualize o segredo e reinicie os processos que usam a API.
5. Confira com GET /me.

Revogar ou desativar#

• Revogar apaga o token e encerra a integração de vez. As chamadas passam a receber 401.
• Desativar (desmarcar Ativa) suspende a integração. As chamadas recebem 401 com a mensagem "Integração inativa ou revogada." até ela ser reativada.

IPs liberados#

O administrador pode restringir a integração a uma lista de endereços, um por linha, aceitando IPs individuais e faixas CIDR:

200.150.10.20
200.150.10.0/24

Lista em branco significa qualquer IP. Uma chamada de fora da lista recebe:

{ "message": "IP não liberado para esta integração." }

com código 403.

Login dos aplicativos#

Os aplicativos do GedFlow entram com o e-mail e a senha de um usuário da prefeitura, e recebem um token por aparelho. Esse fluxo é para aplicativos usados por pessoas. Sistemas de terceiros devem usar uma integração, nunca a senha de um servidor.

Entrar#

curl https://gedflow.com.br/api/v1/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"********","device_name":"iPhone da Ana"}'

Campo	Obrigatório	Descrição
email	sim	E-mail do usuário da prefeitura.
password	sim	Senha do usuário.
device_name	sim	Nome do aparelho (até 120 caracteres). Aparece para o administrador em Aplicativos conectados.

Resposta 201:

{
  "token": "37|Hk2mP9xQ4rT7vW1yZ3bN5cF8gJ0lS6dA2eU4iO7",
  "expires_at": "2026-11-02T14:30:00+00:00",
  "user": { "id": "01J9ZE1A2B3C4D5E6F7G8H9J0K", "name": "Ana Souza", "tenant": "Prefeitura de Exemplo" }
}

• O token vale 30 dias (prazo padrão da plataforma). Depois disso, as chamadas recebem 401 e o aplicativo deve pedir o login de novo.
• E-mail ou senha errados, usuário inativo ou prefeitura inativa: 422 com a mensagem "E-mail ou senha incorretos." no campo email. A resposta é a mesma em todos os casos, de propósito.
• São aceitas 5 tentativas por minuto por IP e e-mail. Acima disso, 429.
• Só usuários da prefeitura entram por aqui. Usuários técnicos de integração e da equipe de digitalização, não.

Sair#

curl -X POST https://gedflow.com.br/api/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN_DO_APARELHO" \
  -H "Accept: application/json"

Resposta 204. Só o token deste aparelho é revogado; os outros aparelhos do mesmo usuário continuam conectados. Chamar logout com um token de integração devolve 403: tokens de integração são revogados pela prefeitura, no painel.

O administrador da prefeitura também pode desconectar qualquer aparelho em Aplicativos conectados. Veja Aplicativos conectados.

O que o aplicativo pode ver#

Exatamente o que o usuário vê no painel: os mesmos setores, a mesma regra de sigilo, os mesmos campos sensíveis e as mesmas permissões. Os aplicativos não usam escopos. Toda consulta fica na trilha de auditoria em nome do usuário.

Erros 401 e 403#

Código	Mensagem típica	O que fazer
401	Não autenticado: envie um token válido no cabeçalho Authorization: Bearer.	Token ausente, digitado errado, trocado, revogado ou (nos aplicativos) expirado. Confira o cabeçalho e peça um token novo se preciso.
401	Integração inativa ou revogada.	A prefeitura desativou ou revogou a integração. Fale com o administrador.
403	IP não liberado para esta integração.	Seu IP de saída não está na lista. Peça a inclusão.
403	A integração não tem o escopo "download".	Falta escopo. Peça ao administrador para incluir, se fizer sentido.
403	Prefeitura inativa.	O contrato da prefeitura está suspenso. Fale com a prefeitura.
403	Setor fora do seu acesso.	Ao cadastrar: o setor não está no recorte da integração.