> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar requisições na API do Portal usando Tokens de Acesso Pessoal

# Autenticação

A API do Portal usa **Bearer Token** no header `Authorization`. O método recomendado para integrações e o **Token de Acesso Pessoal (PAT)**.

## Tipos de credencial

| Tipo                | Quando usar                                         | Como obter                  |
| ------------------- | --------------------------------------------------- | --------------------------- |
| **PAT** (`pat_...`) | Integrações de terceiros, scripts, serviços backend | Painel → Perfil → Segurança |
| **OAuth (JWT)**     | Apps oficiais (Dashboard, Mobile)                   | Fluxo OAuth via Logto       |

Este manual cobre o caso de uso de PAT, que e o canal oficial para integradores externos.

## Criando um PAT

<Steps>
  <Step title="Acesse Perfil → Segurança">
    No painel, clique no seu avatar e va em **Perfil**, depois aba **Segurança**.
  </Step>

  <Step title="Criar Token">
    Clique em **Criar Token**, escolha um nome descritivo (ex: `crm-integration-prod`) e defina a validade.
  </Step>

  <Step title="Copie o token">
    O token começa com `pat_` e e exibido **uma única vez**. Guarde em local seguro (cofre, variável de ambiente).
  </Step>
</Steps>

<Warning>
  Trate o PAT como uma senha. Ele concede acesso integral as suas entidades. Se vazar, revogue imediatamente no mesmo lugar onde foi criado.
</Warning>

## Usando o token

Inclua o header `Authorization` em **toda** requisição:

```bash theme={null}
curl https://portal.unicontrol.me/v1/states \
  -H "Authorization: Bearer pat_seu_token_aqui"
```

Exemplo em Python:

```python theme={null}
import os
import requests

PORTAL_TOKEN = os.environ["PORTAL_TOKEN"]
BASE_URL = "https://portal.unicontrol.me/v1"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {PORTAL_TOKEN}"

resp = session.get(f"{BASE_URL}/states")
resp.raise_for_status()
print(resp.json())
```

Exemplo em Node.js (fetch):

```javascript theme={null}
const PORTAL_TOKEN = process.env.PORTAL_TOKEN;
const BASE_URL = "https://portal.unicontrol.me/v1";

const resp = await fetch(`${BASE_URL}/states`, {
  headers: { Authorization: `Bearer ${PORTAL_TOKEN}` },
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Validade e renovação

PATs podem ser criados com as validades:

* **Nunca expira** — para integrações permanentes em backends controlados.
* **30 / 90 / 365 dias** — para integrações temporarias ou de menor confianca.

Quando o token expira, qualquer requisição retorna `401 Unauthorized`. Não ha refresh: gere um novo token e atualize o segredo na sua integração.

## Revogando um token

Em **Perfil → Segurança**, clique em **Revogar** ao lado do token. A revogação e imediata — todas as requisições subsequentes que usem aquele token receberão `401`.

<Tip>
  Use **um PAT por integração** em vez de reaproveitar o mesmo token em multiplos serviços. Isso permite revogar somente o serviço comprometido sem derrubar os demais.
</Tip>

## Erros comuns

| Status                  | Causa                                     | O que fazer                                             |
| ----------------------- | ----------------------------------------- | ------------------------------------------------------- |
| `401 Unauthorized`      | Token ausente, inválido ou revogado       | Verifique o header e gere um novo PAT se necessário     |
| `403 Forbidden`         | Token válido mas sem permissão no recurso | Veja se opera em outra org (header `X-Organization-Id`) |
| `429 Too Many Requests` | Rate limit estourado                      | Reduza a frequência ou faca upgrade de plano            |

Veja [Limites e Erros](/integrador/limites-e-erros) para o detalhamento completo.