API Keys
Chaves são criadas e gerenciadas no painel da Pitra, em API.
Criação
Ao criar uma chave você define nome, ambiente, scopes e, opcionalmente, uma data de expiração. A secret completa é exibida apenas no momento da criação.
A secret completa não pode ser recuperada depois que o modal de criação/rotação é fechado. Se você perdê-la, rotacione a chave para gerar uma nova.
Scopes
Uma chave só acessa o que os seus scopes permitem. Chamadas fora do escopo devolvem 403 insufficient_scope.
| Scope | Endpoints |
|---|---|
| products:read | GET /products, GET /products/:id |
| products:write | POST /products, PATCH /products/:id, POST /products/:id/archive |
| checkouts:read | GET /checkouts, GET /checkouts/:id |
| checkouts:write | POST /checkouts, POST /checkouts/:id/archive |
| sales:read | GET /sales, GET /sales/:id |
| customers:read | Reservado. Nenhum endpoint público exige este scope hoje. |
| webhooks:read | GET /webhooks, GET /webhooks/:id, GET /webhooks/:id/deliveries |
| webhooks:manage | POST /webhooks, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/test |
Rotação
A rotação gera uma nova secret para a mesma chave e invalida a anterior imediatamente. Atualize a variável de ambiente da sua aplicação antes de rotacionar em produção.
Revogação
Uma chave revogada passa a responder 401 revoked_api_key em todas as requisições. A revogação é definitiva.
Expiração
Se a chave tiver data de expiração, requisições após esse prazo respondem 401 expired_api_key. Chaves sem data configurada não expiram sozinhas.