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 |
Criando um PAT
Acesse Perfil → Segurança
No painel, clique no seu avatar e va em Perfil, depois aba Segurança.
Criar Token
Clique em Criar Token, escolha um nome descritivo (ex: crm-integration-prod) e defina a validade.
Copie o token
O token começa com pat_ e e exibido uma única vez. Guarde em local seguro (cofre, variável de ambiente).
Trate o PAT como uma senha. Ele concede acesso integral as suas entidades. Se vazar, revogue imediatamente no mesmo lugar onde foi criado.
Usando o token
Inclua o header Authorization em toda requisição:
curl https://portal.unicontrol.me/v1/states \
-H "Authorization: Bearer pat_seu_token_aqui"
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())
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.
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.
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 |
