Autenticação

O SantoID oferece dois métodos principais de autenticação para garantir que suas integrações sejam seguras e flexíveis. Escolha o método que melhor se adapta ao seu caso de uso.

Comparativo de Métodos

Característica	API Token Novo	Service Account (JWT)
Tipo	Token Opaco de Longa Duração	Token JWT (eyJ...) de Curta Duração
Expiração	Não expira (revogação manual)	Expira em ~1 hora
Uso	Header x-api-key	Header Authorization: Bearer
Complexidade	Simples (Static Token)	Média (Requer troca de credenciais)
Recomendado para	Integrações Backend-to-Backend, Scripts, Webhooks	Aplicações que requerem rotação frequente

---

1. API Tokens (Recomendado) Novo

O sistema de API Tokens foi desenhado para simplificar a integração, eliminando a necessidade de fluxos complexos de troca de tokens.

:::info Disponibilidade Atualmente, o uso de API Tokens é suportado exclusivamente nos seguintes serviços (Síncronos e Assíncronos):

• Tipificação (Typification)
• OCR
• Face Match

Futuramente, este método será expandido para cobrir mais endpoints da plataforma. :::

Como Utilizar

Para autenticar com um API Token, você deve incluir o cabeçalho x-api-key em suas requisições HTTP.

Exemplo de Header:

x-api-key: SeuTokenGeradoNoPainel...

:::warning Importante O API Token é uma alternativa ao Bearer Token. Utilize um ou outro, nunca ambos na mesma requisição. :::

---

2. Service Accounts (JWT)

A autenticação via Service Account envolve a criação de um token de ID OpenID Connect assinado. Este é o método padrão para operações administrativas e serviços que ainda não suportam API Tokens.

Obtendo uma Conta de Serviço

Através do frontend em https://app.santoid.com.br, navegue até o menu lateral "Identity" e depois "Service Accounts":

Figura 1: Abrir listagem de Contas de Serviço.

Após clicar em "+ Add" e criar uma nova Conta de Serviço, clique em download para obter o arquivo JSON account-data.json:

Figura 2: Baixar arquivo account-data.json.

Nota: Tokens de ID são JSON Web Tokens (JWT) que expiram aproximadamente uma hora após a criação.

Gerando um Token de Acesso

Para realizar requisições na API, você precisa trocar as credenciais da sua Conta de Serviço (account-data.json) por um token de acesso.

1. Codificar o arquivo JSON em Base64

O conteúdo do arquivo account-data.json deve ser codificado em Base64 (sem quebras de linha).

:::tip Ferramenta Útil Você pode realizar essa codificação rapidamente clicando no botão Base64 Encoder localizado no topo da nossa Referência da API. Basta colar o conteúdo do seu arquivo JSON lá. :::

Exemplo via Shell (Linux/Mac):

base64 -w 0 account-data.json

Exemplo via Python:

import base64

with open('account-data.json', 'rb') as f:
    encoded_string = base64.b64encode(f.read()).decode('utf-8')
    print(encoded_string)

2. Solicitar o Token

Envie uma requisição POST para o endpoint de autenticação com o conteúdo codificado.

Endpoint: POST https://api.santoid.com.br/api/v1/service-account/refresh-token

Exemplo de Requisição (cURL):

curl --location 'https://api.santoid.com.br/api/v1/service-account/refresh-token' \
--header 'Content-Type: application/json' \
--data '{
    "service_account_base64": "<SEU_JSON_EM_BASE64>"
}'

Resposta de Sucesso (200):

A API retornará uma string contendo o token JWT.

"eyJhbGciOiJSUzI1NiIsImtpZCI6..."

dica

Este token deve ser enviado no header Authorization de todas as requisições subsequentes: Authorization: Bearer <SEU_TOKEN>

informação

Para mais detalhes técnicos, códigos de erro e para testar a requisição diretamente no navegador, consulte a Referência da API.