Pular para o conteúdo principal

Autenticação

A autenticação envolve a criação de um token de ID OpenID Connect assinado pelo Google. Para gerar o token, você precisa ter uma Conta de Serviço.

Aqui está um exemplo de como obter 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.

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.

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. Decodifique o token e verifique o tempo exp (unix epoch em segundos) para ver se precisa atualizá-lo.

Exemplo da estrutura do JWT decodificado​

{
    "iss": <string>,
    "azp": <string>,
    "aud": <string>,
    "sub": <string>,
    "hd": <string>,
    "email": <string>,
    "email_verified": <bool>,
    "at_hash": <string>,
    "iat": <int>,
    "exp": <int>
}

Como decodificar o token​

Via Shell​

sudo apt install jq -y
jq -R 'split(".") | .[1] | @base64d | fromjson' <<< "<substitua pelo seu token aqui>"

Via Python (requer pacote PyJWT)​

import jwt

decoded = jwt.decode(<token>, options={"verify_signature": False})
# exp é o tempo de expiração do token em inteiro no formato Unix Epoch
exp = decoded["exp"]

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).

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>

info

Para mais detalhes técnicos e outros códigos de resposta, consulte a Referência da API.