Autenticação

Bearer tokens com prefixo manu_, scopes granulares e expiração opcional. Como criar, rotacionar e revogar com segurança.

A API do MIXY CRM autentica via Bearer tokens. Não há OAuth para integrações server-side — o modelo é simples e robusto: você cria um token no app, envia no header Authorization, e ele identifica seu workspace e suas permissões.

Formato do token

Todo token tem o formato:

Text

manu_<base64url-32-bytes>

Os primeiros 12 caracteres (manu_xxxxxxx) são o prefixo — é o que fica visível depois de criado, pra você reconhecer qual token foi usado em um log ou em uma chamada suspeita.

O token completo aparece uma única vez no momento da criação. O servidor só armazena um hash SHA-256, nunca o token em plaintext.

Enviando o token

Text

curl https://api.mixycrm.com.br/api/v1/people \
  -H "Authorization: Bearer manu_seu_token_aqui"

Em JavaScript (Node 18+ ou navegador moderno):

Text

const res = await fetch("https://api.mixycrm.com.br/api/v1/people", {
  headers: {
    Authorization: `Bearer ${process.env.MIXY_TOKEN}`,
    "Content-Type": "application/json",
  },
});

Em Python:

Text

import os, requests

res = requests.get(
    "https://api.mixycrm.com.br/api/v1/people",
    headers={"Authorization": f"Bearer {os.environ['MIXY_TOKEN']}"},
)

Nunca em código de browser

Tokens são credenciais server-side. Nunca os exponha em JavaScript que roda no navegador, em apps mobile sem proxy intermediário, ou em repositórios públicos. Se um token vazou, vá em Configurações → API Tokens → Revogar.

Scopes

Scopes controlam o que o token pode fazer.

Scopes legados (simples)

read — apenas GET. Útil pra dashboards, exportações, BI.
read_write — GET, POST, PATCH, DELETE em todos os recursos.

Scopes granulares (recomendado em produção)

Scope	O que libera
`*`	Wildcard — equivalente a `read_write`.
`crm:person:read`	GET em `/people`.
`crm:person:write`	POST/PATCH/DELETE em `/people`.
`crm:company:read`	GET em `/companies`.
`crm:company:write`	POST/PATCH/DELETE em `/companies`.
`crm:deal:read`	GET em `/deals`.
`crm:deal:write`	POST/PATCH/DELETE em `/deals`.
`crm:activity:read`	GET em `/activities`.
`crm:activity:write`	POST em `/activities`.
`crm:automation:read`	Leitura de automações (interno, futuro v1).
`crm:automation:write`	Escrita de automações (interno, futuro v1).
`crm:webhook:manage`	Gerenciar webhooks de saída.
`marketplace:read`	Listar apps e instalações.
`marketplace:install`	Instalar/desinstalar apps via API.
`contracts:read`	Leitura de contratos (módulo Contracts).
`contracts:write`	Escrita de contratos.

Princípio do menor privilégio

Para uma integração que só lê dados pra um BI, use apenas crm:*:read. Para um formulário que cria leads, use só crm:person:write. Tokens overpermitidos aumentam o blast radius caso vazem.

Expiração

Ao criar um token, você pode definir uma data de expiração. Recomendado:

30 dias para tokens em desenvolvimento.
90 dias para tokens de produção, com alerta de rotação automática.
Sem expiração apenas para tokens guardados em vault/secrets manager com auditoria.

Tokens expirados retornam 401 com code: "unauthorized".

Rotação de tokens

Boa prática: rotacionar trimestralmente. Fluxo recomendado:

Crie um novo token com o mesmo scope do antigo.
Atualize a credencial no consumidor (servidor, secrets manager, etc.).
Verifique que o novo token está sendo usado e o antigo não recebeu nenhuma chamada nas últimas 24h.
Revogue o antigo em Configurações → API Tokens.

A revogação é imediata — o token vira inválido em < 1s globalmente.

Identificação multi-tenant

Cada token está vinculado a um workspace (tenant) específico. Não há conceito de "token mestre" entre workspaces. Se você precisa operar em múltiplos workspaces, gere um token por workspace.

O servidor identifica o workspace pelo token e aplica isolamento em todas as queries via PostgreSQL Row-Level Security — mesmo que dois workspaces tenham IDs colidindo, é fisicamente impossível um vazar dados do outro.

Erros de autenticação

Status	Código	Causa típica
401	`unauthorized`	Header `Authorization` ausente, mal formado, ou token revogado/expirado.
403	`forbidden`	Token válido, mas faltou scope pra a operação.
403	`plan_limit`	Quota do plano atual atingida.

Veja o formato completo em Erros.