> ## Documentation Index > Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt > Use this file to discover all available pages before exploring further. # Autenticação > Chaves de API, bearer tokens, idempotência e tenancy por organização. A API da Caratuva suporta dois esquemas de autenticação: | Esquema | Header | Usado por | | ------------ | ------------------------------------ | ------------------------------------------------- | | Chave de API | `X-API-Key: pk__.` | Clientes servidor-a-servidor do lado do vendedor. | | Bearer JWT | `Authorization: Bearer ` | Sessões do painel. | Para integradores B2B, a chave de API é a credencial que você usará em toda parte. JWTs são emitidos para o frontend do painel e não são diretamente relevantes para integrações servidor-a-servidor. ## Chaves de API Uma chave de API tem o formato: ``` pk__. ``` * `` é `test` ou `live`. * `` é a metade pública de lookup — seguro para logar. * `` aparece exatamente uma vez na criação. A Caratuva guarda só um hash; o texto plano não é recuperável. Se perder, revogue a chave e crie uma nova. Veja [Chaves de API](/pt-BR/api-reference/api-keys) para emissão, listagem, revogação, escopos e rotação. ## Tenancy Toda requisição autenticada resolve para uma organização derivada da credencial — a claim `orgId` do JWT ou a organização dona da chave de API. Não há override por header; tenancy é sempre carregada pela credencial. Isso significa: * Uma chave de API nunca pode agir em nome de outra organização, independente dos headers. * Uma chave vazada afeta exatamente uma organização, e você pode revogá-la sem mexer em nenhuma outra. * Todos os endpoints de leitura escopam automaticamente para sua organização. Você nunca lista nem busca dados de outra. ## Idempotência Endpoints que criam recursos (`POST /v1/invoices` e `POST /v1/payment-intents`) aceitam um header `Idempotency-Key`. O valor recomendado é um UUID novo por operação lógica. ``` Idempotency-Key: ``` Comportamento: * A primeira criação com uma determinada chave cria o recurso. * Um replay com a mesma chave retorna o **recurso existente**, re-serializado a partir do armazenamento — então o payload reflete o estado *atual* do recurso (não uma cópia byte a byte da resposta original), e nenhum efeito colateral roda duas vezes. * A correspondência é feita **apenas pela chave** — o corpo da requisição *não* é comparado. Um replay com a mesma chave mas um corpo *diferente* ainda retorna o recurso original; o novo corpo é ignorado. Use uma chave nova sempre que pretender criar um recurso diferente. * A idempotência é chaveada por `(organização, chave)` no recurso criado e **não tem expiração** — replays permanecem idempotentes durante toda a vida daquele recurso. * Se uma chave já estiver vinculada a um recurso criado por um caminho *diferente* (por exemplo, uma invoice do dashboard quando você faz `POST /v1/payment-intents`), a API retorna `409 IdempotencyKeyConflict` — use uma chave nova. Sempre envie uma chave de idempotência em retentativas — erros de rede e 5xx transitórios acontecem, e o padrão seguro é "envie de novo com a mesma chave". ## Modo teste vs. produção Chaves com prefixo `pk_test_` são reconhecidas como credenciais de modo teste. O modo teste roda o fluxo inteiro de ponta a ponta — KYC, coleta de pagamento, câmbio, liquidação, webhooks — contra uma instância de pagamento sandbox. **KYB e KYC do comprador são aprovados automaticamente, e nenhum dinheiro real se move.** Veja [Ambientes](/pt-BR/api-reference/environments) para saber como o modo é carregado em cada requisição. Use o modo teste para: * Desenvolvimento local. * Testes de CI / integração. * Ambientes de staging. * Demonstrações. Modos teste e produção são totalmente isolados. Faturas de teste, compradores de teste e entregas de webhook de teste ficam em um dataset separado; nunca aparecem no painel de modo produção e vice-versa. Chaves `pk_live_*` batem nos trilhos reais. Nunca use fora de produção. ## CORS A API aceita requisições cross-origin via navegador apenas das origens web próprias da Caratuva que estão na allowlist (o painel, o portal hospedado do comprador e o site de marketing); ela não é aberta a origens de navegador arbitrárias. Sua integração B2B deve chamar a API **servidor-a-servidor** — nunca embuta uma chave de API em código de navegador. Fluxos do lado do comprador passam pela página de pagamento hospedada em `pay.caratuva.com`, não pelo seu próprio código de browser. ## Tempo A API retorna timestamps em RFC 3339 / ISO 8601 com timezone explícita (`2026-05-02T14:00:00.000Z`). Sempre envie timestamps com timezone; horários locais sem timezone são rejeitados. ## Content type Requisições e respostas são `application/json`. A API rejeita requisições sem `Content-Type: application/json` em endpoints de escrita. ## Dicas de log * A metade `` da chave de API é segura para logar; a metade `` não. * O header `Idempotency-Key` é seguro para logar e útil para tracing. * Não logue headers `Authorization: Bearer ` — JWTs são curto-prazo, mas ainda secretos.