# Chave, ambiente e limite

Como a chave autentica, o que ela abre, em que ambiente fala, quanto aguenta e o que fica registrado.

## A chave decide o ambiente

| Prefixo | Ambiente | Endereço |
| --- | --- | --- |
| `ksk_test_` | Piloto, numa empresa de teste | `https://stag.kernos.com.br` |
| `ksk_live_` | Produção | `https://api.kernos.com.br` |

Mande a chave em `Authorization: Bearer ksk_…`. O prefixo escolhe o endereço: com SDK você nunca configura URL. Chave do outro ambiente recusa com [`api_key_wrong_environment`](/erros/api_key_wrong_environment.md).

## O que a chave abre

A chave tem **ações** (`sales_order.import`, `product.list`…, o id que a página de cada rota mostra) e, se quiser, uma lista de CDs. Fora delas, a rota recusa com [`api_key_action_not_granted`](/erros/api_key_action_not_granted.md). Quem cria e gira a chave é quem gere a empresa; uma chave nunca cria outra. A chave só vale nas rotas desta referência: em qualquer outra, [`api_key_out_of_scope`](/erros/api_key_out_of_scope.md).

A chave tem validade opcional. Vencida, recusa com [`api_key_expired`](/erros/api_key_expired.md). A chave inteira aparece **uma vez**, na criação; depois só os 4 últimos caracteres.

## Cabeçalhos

| Cabeçalho | Para quê |
| --- | --- |
| `Authorization` | `Bearer ksk_…`. |
| `Kernos-Version` | A versão do contrato (`2026-10-03`). Sem ele, a mais nova. A resposta sempre diz qual usou, no mesmo cabeçalho. |
| `Idempotency-Key` | Um UUID por escrita (POST, PUT, PATCH, DELETE). Repetida com o mesmo corpo, devolve a mesma resposta sem escrever de novo; com corpo diferente, [`idempotency_key_reused`](/erros/idempotency_key_reused.md). |

## A resposta

Toda resposta é o envelope `{ ok, data, error, error_code, field, trace_id }`. Com `ok: true`, o resultado vem em `data`. Com `ok: false`, decida pelo `error_code` (estável), mostre o `error` (a frase em português) e, se for falar com a Kernos, mande o `trace_id`. Veja os [erros](/erros.md).

## O limite

Cada chave pode fazer **25 pedidos por segundo** em `ksk_live_` e **10** em `ksk_test_`. Passou: HTTP 429 [`rate_limited`](/erros/rate_limited.md) com `Retry-After` em segundos. Os SDKs esperam e repetem até 2 vezes, no 429, no 5xx e na falha de rede; nunca num 4xx.

## O registro de pedidos

A Kernos guarda cada pedido da chave por 30 dias: rota, status, código de recusa e duração. `GET /v1/requests` lista os da própria chave e `GET /v1/requests/{request_id}` mostra um. Na chave de **teste**, o registro guarda também o corpo da resposta (até 8 KB); na de produção, nunca guarda corpo. O `request_id` é o `X-Request-Id` que você mandou ou o que a Kernos gerou.