> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sherlocker.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Autenticação
> Como autenticar nas APIs dos Motores de Análise com chave Bearer
Toda requisição à API `/v1` — tanto do [Motor de CPF/CNPJ](/motor-analise/introducao) quanto do [Motor de Borderô](/credito/introducao) — exige uma chave de API no header `Authorization`, no formato Bearer:
```
Authorization: Bearer slhk_sua_chave_aqui
```
As chaves têm o prefixo `slhk_` e são vinculadas ao seu workspace no Sherlocker. **Uma única chave serve os dois motores**: se você já integra um deles, use a chave que já tem no outro.
**Diferente do restante das docs deste site.** As demais APIs documentadas aqui (221b-api) autenticam via query param `?token=`. Os Motores de Análise usam a **mesma base** (`https://221b-api.sherlocker.com.br/api/v1`), mas **não aceitam** token em query param — apenas o header `Authorization: Bearer slhk_`.
## Criar e guardar a chave
Acesse **Settings → API Keys** no app Sherlocker e crie uma nova chave.
A chave é exibida **uma única vez**. Depois de fechar a tela, não é possível vê-la de novo.
Armazene em um secret manager ou variável de ambiente. Nunca comite a chave no repositório nem a exponha em código de frontend.
Se perder ou suspeitar de vazamento, revogue a chave no app e crie uma nova. Chaves revogadas passam a responder `401`.
## Exemplo mínimo
Um `GET` em um run inexistente serve como teste rápido da chave — não debita tokens. Resposta `404 not_found` significa que a autenticação funcionou; `401` indica problema na chave; `403 feature_not_enabled` indica chave válida, mas workspace sem a feature `analysis_engine` — veja a tabela abaixo. O mesmo teste vale para o Motor de Borderô, trocando o path por `/operations/`.
```bash cURL theme={null}
curl -i "https://221b-api.sherlocker.com.br/api/v1/analyses/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer slhk_sua_chave_aqui"
```
```python Python theme={null}
import requests
resp = requests.get(
"https://221b-api.sherlocker.com.br/api/v1/analyses/00000000-0000-0000-0000-000000000000",
headers={"Authorization": "Bearer slhk_sua_chave_aqui"}
)
print(resp.status_code)
print(resp.json())
```
```javascript Node.js theme={null}
const resp = await fetch(
"https://221b-api.sherlocker.com.br/api/v1/analyses/00000000-0000-0000-0000-000000000000",
{ headers: { Authorization: "Bearer slhk_sua_chave_aqui" } }
);
console.log(resp.status);
console.log(await resp.json());
```
Os Motores usam a **mesma base** da API 221b (`https://221b-api.sherlocker.com.br/api/v1`), mas autenticam via `Authorization: Bearer slhk_…` — **não** via `?token=`.
## Falhas de autenticação e acesso
Todos os erros seguem o formato RFC 7807 (`Content-Type: application/problem+json`). Use o campo `code` para tratamento programático — detalhes em [Erros](/motor-analise/erros).
| Situação | HTTP | `code` | Como resolver |
| ----------------------------------------------------------- | ---- | --------------------- | --------------------------------------------------------- |
| Header `Authorization` ausente ou malformado | 401 | `unauthorized` | Envie `Authorization: Bearer slhk_` |
| Chave inválida | 401 | `unauthorized` | Confira se copiou a chave completa, com o prefixo `slhk_` |
| Chave revogada | 401 | `unauthorized` | Crie uma nova chave em Settings → API Keys |
| Feature `analysis_engine` desabilitada no workspace | 403 | `feature_not_enabled` | Solicite acesso pela `request_access_url` do body |
| Feature `analysis_engine_pf` desabilitada (análises de CPF) | 403 | `feature_not_enabled` | Solicite acesso pela `request_access_url` do body |
O acesso à API é liberado por workspace: a feature `analysis_engine` cobre qualquer chamada `/v1` — os dois motores, incluindo `POST /operations` — e análises de CPF exigem adicionalmente a feature `analysis_engine_pf`.
**Exemplo de `401`:**
```json theme={null}
{
"type": "https://docs.sherlocker.com.br/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "The Authorization header is missing, malformed, or the API key is invalid or revoked.",
"instance": "/v1?request_id=req-uuid-here"
}
```
**Exemplo de `403 feature_not_enabled`:**
```json theme={null}
{
"type": "https://docs.sherlocker.com.br/problems/feature_not_enabled",
"title": "Feature Not Enabled",
"status": 403,
"code": "feature_not_enabled",
"detail": "The analysis_engine feature is not enabled for this workspace. To request access visit https://docs.sherlocker.com.br/api/access or contact support at https://docs.sherlocker.com.br/support.",
"request_access_url": "https://docs.sherlocker.com.br/api/access",
"instance": "/v1?request_id=req-uuid-here"
}
```
## Tracing com `x-request-id`
O header `x-request-id` é opcional em toda requisição. Se você não enviar, o servidor gera um UUID. Em qualquer caso, o identificador é:
* ecoado no header `x-request-id` da resposta;
* incluído no campo `request_id` do body das respostas de sucesso;
* incluído no campo `instance` dos erros, no formato `/v1?request_id=`.
Envie o seu próprio `x-request-id` para correlacionar as chamadas com os logs do seu sistema. Ao acionar o suporte, informe o valor de `instance` (ou o `request_id`) — é assim que a requisição é localizada nos logs do servidor.
```bash cURL theme={null}
curl "https://221b-api.sherlocker.com.br/api/v1/analyses/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer slhk_sua_chave_aqui" \
-H "x-request-id: meu-trace-id-123"
```
```python Python theme={null}
import requests
resp = requests.get(
"https://221b-api.sherlocker.com.br/api/v1/analyses/00000000-0000-0000-0000-000000000000",
headers={
"Authorization": "Bearer slhk_sua_chave_aqui",
"x-request-id": "meu-trace-id-123"
}
)
print(resp.headers["x-request-id"])
```
```javascript Node.js theme={null}
const resp = await fetch(
"https://221b-api.sherlocker.com.br/api/v1/analyses/00000000-0000-0000-0000-000000000000",
{
headers: {
Authorization: "Bearer slhk_sua_chave_aqui",
"x-request-id": "meu-trace-id-123"
}
}
);
console.log(resp.headers.get("x-request-id"));
```
## Próximos passos
Crie sua primeira análise de CNPJ ou CPF
Analise seu primeiro borderô CNAB 400
Formato RFC 7807 e o registro completo de codes
Header Idempotency-Key e retries seguros