---
title: Autenticação
description: Fluxo OAuth2 JWT Bearer utilizado por todos os contratos do IDCloud. Saiba como obter credenciais, construir a asserção JWT e trocá-la por um token de acesso.
canonical: https://developer.unico.io/pt-BR/developers/start/authentication
locale: pt-BR
generated_by: markdown-export
---

- [/pt-BR/](/pt-BR/)
- [Começar](/pt-BR/developers/start/)
- Autenticação

**Nesta página# Autenticação

Todas as APIs do IDCloud (contratos Web & SDK e API) utilizam **OAuth2 com JWT Bearer Grant Type** ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)). 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 clienteA 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 ambienteMantenha 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
ClaimValorNotas`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. 3600Não pode ultrapassar 1 hora a partir de `iat`
```
{  "iss": "my-account@abc123.iam.acesso.io",  "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 extrasQualquer 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:
AmbienteEndpoint**Produção**`POST https://identity.acesso.io/oauth2/token`**UAT**`POST https://identityhomolog.acesso.io/oauth2/token`
Request
ParâmetroValor`Content-Type``application/x-www-form-urlencoded``grant_type``urn:ietf:params:oauth:grant-type:jwt-bearer``assertion`Seu JWT assinado
cURLNode.jsPython```
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: 'my-account@abc123.iam.acesso.io',    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 timeimport jwt  # PyJWTimport requestswith open("private-key.pem", "rb") as f:    private_key = f.read()now = int(time.time())assertion = jwt.encode(    {        "iss": "my-account@abc123.iam.acesso.io",        "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}
```

CampoTipoDescrição`access_token`stringToken de acesso JWT. Use em `Authorization: Bearer <token>` em todas as chamadas da API.`expires_in`integerTempo de expiração em segundos. Exemplo: `3600`.`token_type`stringSempre `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:
ContratoHost de ProduçãoHost 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`](/pt-BR/assets/files/authentication-1d221f9a7230435e9c390ba98dac7321.yaml).
MétodoCaminhoDescrição`POST``/oauth2/token`Troca uma asserção JWT assinada por um token de acesso Bearer
### Códigos de erro​

CódigoDescriçãoAção`1.0.1`O ID fornecido na formação do `iss` está incorretoVerifique se o campo `iss` corresponde ao ID do tenant fornecido quando a chave privada foi gerada`1.0.14`Aplicação não está ativaVerifique com o gestor do projeto se a aplicação utilizada está ativa`1.1.1`O parâmetro `scope` não foi fornecidoAdicione `"scope": "*"` ao seu payload JWT`1.2.4`Asserção JWT inválidaA 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 JWTO 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álidaA chave privada usada para assinar o JWT não é mais aceita. Solicite novas credenciais para a conta`1.2.7`JWT já utilizadoO 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á ativaA conta utilizada não está ativa`1.2.14`Conta sem as permissões necessáriasA conta utilizada não possui as permissões necessárias`1.2.18`Conta temporariamente bloqueadaA 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 autorizadaO 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 JWTFalha ao decodificar o JWT. Verifique o formato do token e se foi assinado com RS256.`1.2.21`Chave privada incorreta / Falha na autenticaçãoA 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 payloadO 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 IPSeu IP não está na lista de permissões desta conta`1.3.2`Restrição de acesso por horárioA requisição está fora da janela de horário permitida para esta conta
### Próximos passos​

[Ambientes](/pt-BR/developers/start/environments) — sandbox vs hosts de produção
Web & SDK — Criar Processo — primeira chamada após autenticação
[API — Criar Processo](/pt-BR/developers/api-reference/post-processes) — primeira chamada após autenticação
[SSO / SAML](/pt-BR/developers/start/sso-saml) — autentique seus usuários nos portais de produtos da Unico com o seu próprio provedor de identidade, em vez do fluxo servidor a servidor acima
Última atualização em 8 de out. de 2026**