Autenticação

Todas as APIs do IDCloud (contratos Web & SDK e API) utilizam OAuth2 com JWT Bearer Grant Type (RFC 7523). Você gera uma asserção JWT de curta duração no seu back-end, troca-a por um token Bearer e usa esse token em todas as chamadas subsequentes.

Nunca faça isso no lado do cliente

A asserção JWT deve ser gerada somente no seu back-end. Nunca exponha sua chave privada em código front-end, aplicativos móveis, repositórios ou logs.

Obtendo credenciais

Antes de gerar tokens, você precisa de uma conta de serviço provisionada pela Unico. Entre em contato com o suporte da Unico e forneça:

Nome da conta de serviço (máx. 12 caracteres)
Nome, e-mail e telefone do responsável (somente números do Brasil, EUA ou México)

Você receberá:

Nome único da conta
ID do tenant
Payload JWT base
Arquivo de chave privada (formato .pem)

Uma conta por ambiente

Mantenha contas de serviço separadas para UAT e Produção.

Construindo a asserção JWT

A asserção é um JWT no formato JWS compacto: {Base64url(Header)}.{Base64url(Payload)}.{Base64url(Signature)}.

Header

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload

Claim	Valor	Notas
`iss`	`<account_name>@<tenant_id>.iam.acesso.io`	Fornecido com suas credenciais
`aud`	`https://identityhomolog.acesso.io` (UAT) ou `https://identity.acesso.io` (Produção)	Deve corresponder ao host do endpoint de token
`scope`	`*`	Concede todas as permissões
`iat`	Timestamp Unix (segundos)	Hora em que o JWT foi emitido
`exp`	`iat` + máx. 3600	Não pode ultrapassar 1 hora a partir de `iat`

{
  "iss": "[email protected]",
  "aud": "https://identity.acesso.io",
  "scope": "*",
  "iat": 1738086000,
  "exp": 1738089600
}

Signature

Assine o header + payload usando RS256 (RSA + SHA-256) com a chave privada .pem fornecida pela Unico.

Não adicione claims extras

Qualquer campo não listado acima (ex.: sub, jti, nbf) causará um erro 1.2.22. Use apenas os claims indicados.

Solicitando o token

O endpoint de token é o mesmo para ambos os contratos:

Ambiente	Endpoint
Produção	`POST https://identity.acesso.io/oauth2/token`
UAT	`POST https://identityhomolog.acesso.io/oauth2/token`

Request

Parâmetro	Valor
`Content-Type`	`application/x-www-form-urlencoded`
`grant_type`	`urn:ietf:params:oauth:grant-type:jwt-bearer`
`assertion`	Seu JWT assinado

cURL
Node.js
Python

curl -X POST https://identity.acesso.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

import jwt from 'jsonwebtoken';
import fs from 'fs';
import qs from 'querystring';

const privateKey = fs.readFileSync('./private-key.pem');
const now = Math.floor(Date.now() / 1000);

const assertion = jwt.sign(
  {
    iss: '[email protected]',
    aud: 'https://identity.acesso.io',
    scope: '*',
    iat: now,
    exp: now + 3600,
  },
  privateKey,
  { algorithm: 'RS256' }
);

const res = await fetch('https://identity.acesso.io/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: qs.stringify({
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion,
  }),
});

const { access_token, expires_in } = await res.json();

import time
import jwt  # PyJWT
import requests

with open("private-key.pem", "rb") as f:
    private_key = f.read()

now = int(time.time())

assertion = jwt.encode(
    {
        "iss": "[email protected]",
        "aud": "https://identity.acesso.io",
        "scope": "*",
        "iat": now,
        "exp": now + 3600,
    },
    private_key,
    algorithm="RS256",
)

response = requests.post(
    "https://identity.acesso.io/oauth2/token",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": assertion,
    },
)

token_data = response.json()
access_token = token_data["access_token"]

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Campo	Tipo	Descrição
`access_token`	string	Token de acesso JWT. Use em `Authorization: Bearer <token>` em todas as chamadas da API.
`expires_in`	integer	Tempo de expiração em segundos. Exemplo: `3600`.
`token_type`	string	Sempre `Bearer`.

Usando o token

Adicione o token ao header Authorization de cada requisição da API. O header é idêntico para ambos os contratos — o que difere é o host e o caminho da API que você está chamando:

Contrato	Host de Produção	Host de UAT
Web & SDK	`https://api.idcloud.unico.app`	`https://api.idcloud.uat.unico.app`
API	`https://api.id.unico.app`	`https://api.id.uat.unico.app`

Web & SDK — Authorization é o único header de autenticação necessário:

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API — Authorization é utilizado junto com o header APIKEY:

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Renovação do token

Os tokens expiram após 3600 segundos. Implemente a renovação proativa no seu back-end:

Rastreie expires_in da resposta do token e armazene o timestamp de expiração.
Solicite um novo token quando restar 10 minutos ou menos antes da expiração.
Nunca aguarde um 401 em produção para acionar uma renovação.

Referência da API

A especificação OpenAPI completa do endpoint de token está disponível em authentication.yaml.

Método	Caminho	Descrição
`POST`	`/oauth2/token`	Troca uma asserção JWT assinada por um token de acesso Bearer

Códigos de erro

Código	Descrição	Ação
`1.0.1`	O ID fornecido na formação do `iss` está incorreto	Verifique se o campo `iss` corresponde ao ID do tenant fornecido quando a chave privada foi gerada
`1.0.14`	Aplicação não está ativa	Verifique com o gestor do projeto se a aplicação utilizada está ativa
`1.1.1`	O parâmetro `scope` não foi fornecido	Adicione `"scope": "*"` ao seu payload JWT
`1.2.4`	Asserção JWT inválida	A asserção JWT não é mais válida. Duas causas: (a) o tempo atual ultrapassou `exp` (JWT verdadeiramente expirado — gere uma nova asserção para cada solicitação de token); ou (b) `exp` ultrapassa `iat + 3600` (tempo de vida muito longo — limite `exp` a `iat + 3600`).
`1.2.5`	Falha na validação do JWT	O JWT não pode ser validado. Verifique os parâmetros e certifique-se de que foi assinado com RS256 e a chave privada correta
`1.2.6`	Chave privada não é mais válida	A chave privada usada para assinar o JWT não é mais aceita. Solicite novas credenciais para a conta
`1.2.7`	JWT já utilizado	O JWT não é mais aceito, pois já foi utilizado. Gere uma nova asserção para cada solicitação de token
`1.2.11`	Conta não está ativa	A conta utilizada não está ativa
`1.2.14`	Conta sem as permissões necessárias	A conta utilizada não possui as permissões necessárias
`1.2.18`	Conta temporariamente bloqueada	A conta foi temporariamente bloqueada por exceder o número de tentativas de autenticação inválidas
`1.2.19`	Impersonificação de usuário não autorizada	O JWT contém um claim `sub` apontando para uma conta que não está autorizada para impersonificação. Remova o claim `sub` do payload.
`1.2.20`	Falha na decodificação do JWT	Falha ao decodificar o JWT. Verifique o formato do token e se foi assinado com RS256.
`1.2.21`	Chave privada incorreta / Falha na autenticação	A assinatura do JWT não pôde ser verificada com nenhuma chave conhecida para esta conta. Certifique-se de usar a chave privada `.pem` correta para esta conta de serviço e ambiente.
`1.2.22`	Campos não permitidos no payload	O JWT contém campos de payload extras que não são permitidos. Remova quaisquer claims não listados neste guia (ex.: `sub`, `jti`, `nbf`). Observação: se você incluiu um claim `sub` e recebeu `1.2.19`, esse erro tem precedência.
`1.3.1`	Restrição de acesso por IP	Seu IP não está na lista de permissões desta conta
`1.3.2`	Restrição de acesso por horário	A requisição está fora da janela de horário permitida para esta conta

Próximos passos

Ambientes — sandbox vs hosts de produção
Web & SDK — Criar Processo — primeira chamada após autenticação
API — Criar Processo — primeira chamada após autenticação

Obtendo credenciais​

Construindo a asserção JWT​

Solicitando o token​

Usando o token​

Renovação do token​

Referência da API​

Códigos de erro​

Próximos passos​