Referência
Autenticação
Toda requisição é autenticada pelo header X-API-Key, que identifica o workspace e suas permissões.
Toda requisição à API precisa do header:
X-API-Key: vnd_...A chave é a identidade do seu workspace. A partir dela a API sabe:
- Qual workspace está sendo acessado — todo dado lido ou escrito é filtrado por esse workspace. Uma chave nunca enxerga dados de outro workspace.
- Quais permissões (escopos) a chave tem — veja Chaves e escopos.
Formato da chave
- Toda chave começa com o prefixo
vnd_. - O CRM guarda apenas um hash SHA-256 da chave, nunca o texto puro. Por isso a chave é exibida uma única vez na criação.
Exemplo
curl "{BASE_URL}/api-v1-deals?limit=10" \
-H "X-API-Key: vnd_sua_chave_aqui"Quando a autenticação falha
A verificação de credencial acontece antes de qualquer processamento. Possíveis respostas:
| Situação | HTTP | code | message |
|---|---|---|---|
Header X-API-Key ausente | 401 | missing_api_key | "API Key ausente no cabeçalho X-API-Key." |
Chave sem o prefixo vnd_ ou inexistente | 401 | invalid_api_key | "API Key inválida." |
| Chave revogada ou inativa | 401 | revoked_api_key | "API Key revogada ou inativa." |
Quando a chave é válida mas não tem o escopo exigido pelo endpoint, a resposta é
403 insufficient_scope — veja Erros.
A API não usa OAuth nem token de usuário. A única credencial é a API Key no header
X-API-Key. Não é necessário enviar nenhum outro cabeçalho de autorização.