> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Autenticação > Como autenticar suas requisições à API da Chargefy — API keys de organização, API keys de plataforma e o token de usuário do dashboard. A Chargefy tem **duas superfícies de autenticação**, cada uma para um tipo de cliente. Saber qual você usa é o primeiro passo de qualquer integração. | Superfície | Quem usa | Como autentica | | ---------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------ | | **API pública** (`https://api.chargefy.io/v1`) | Integrações server-to-server (seu backend, parceiros, automações) | **API key** no header `Authorization: Bearer` | | **Dashboard** (`dashboard.chargefy.io`) | Pessoas logadas no painel | Token de sessão (JWT) gerenciado pela própria UI | **Você quase sempre quer uma API key.** O token de usuário existe só para a interface do dashboard funcionar — ele não é emitido para você colar em scripts. Se está escrevendo código que fala com a Chargefy de um servidor, use uma API key. Esta página foca nela. A base de toda chamada autenticada é `https://api.chargefy.io/v1`. Cada organização gera as próprias chaves no dashboard, em **Settings → Chaves de API**. ## Tipos de chave Existem **dois tipos** de API key, e eles se comportam de formas diferentes. A diferença não está no formato do token — está em **sobre qual organização a chave pode agir**. | Tipo | Age sobre | Header `Organization` | Caso de uso | | ------------------------ | --------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- | | **Chave de organização** | Somente a própria organização que emitiu a chave | Ignorado — a chave já fixa a org | Você integra a sua própria conta Chargefy | | **Chave de plataforma** | Qualquer organização conectada **ativa** sob a plataforma | **Obrigatório** para escolher a org-alvo | Você opera uma plataforma/marketplace e age em nome das organizações conectadas | **Regra que não muda:** uma chave de organização **não pode** sobrescrever a organização via header. Ela atua exclusivamente na própria org. Só a chave de plataforma usa o header `Organization` para mirar uma organização conectada. ## Formato do token ``` ch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx └┬─┘ └─┬┘ └────────────────┬────────────────┘ │ │ │ │ │ └── parte aleatória (base64url) │ └── ambiente (live | test) └── prefixo Chargefy ``` Todo token começa com `ch_` e carrega o ambiente no prefixo: | Prefixo | Ambiente | Comportamento | | ----------- | -------- | ------------------------------------------------ | | `ch_live_…` | **live** | Cobranças reais. `livemode: true` nas respostas. | | `ch_test_…` | **test** | Sandbox. `livemode: false` nas respostas. | O token aparece **uma única vez**, no momento da criação. A Chargefy guarda apenas um hash — não há como recuperar o texto claro depois. Se perder, revogue e crie uma nova. ## Como usar Envie o token no header `Authorization` com o esquema `Bearer`. Esta é a forma recomendada e compatível com qualquer cliente HTTP. ```bash cURL theme={} curl https://api.chargefy.io/v1/products \ -H "Authorization: Bearer {{API_KEY}}" ``` ```typescript Node theme={} const response = await fetch('https://api.chargefy.io/v1/products', { headers: { Authorization: `Bearer ${process.env.CHARGEFY_API_KEY}`, }, }); ``` ```python Python theme={} import os, requests requests.get( "https://api.chargefy.io/v1/products", headers={"Authorization": f"Bearer {os.environ['CHARGEFY_API_KEY']}"}, ) ``` ### Header alternativo Como alternativa ao `Authorization`, a API também aceita o header dedicado `X-Chargefy-Api-Key`. Use quando o `Authorization` já estiver reservado para outra coisa no seu cliente. ```bash theme={} curl https://api.chargefy.io/v1/products \ -H "X-Chargefy-Api-Key: {{API_KEY}}" ``` Se ambos os headers chegarem, o `X-Chargefy-Api-Key` tem prioridade. Em qualquer um dos dois, o token precisa começar com `ch_` — caso contrário a requisição é tratada como sem credencial. ## Agindo como uma plataforma Se a sua chave é de **plataforma**, ela não tem uma organização fixa: você escolhe a organização conectada a cada request com o header `Organization`. ```bash theme={} curl https://api.chargefy.io/v1/products \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Organization: id_123" ``` O valor de `Organization` é o `id` de uma organização **conectada e ativa** sob a sua plataforma. Sem `Organization`, a plataforma não sabe sobre qual organização agir. O endpoint que exige escopo da org responde `400` pedindo o header. Se o `Organization` aponta para uma org que não é conectada ativa da sua plataforma, a request é negada com `403`. Uma chave de organização **ignora** o header `Organization` — ela só age na própria org. Não é possível usá-la para "saltar" para outra organização. ## Escopos Toda chave carrega um ou mais escopos que limitam o que ela pode fazer. Os escopos são fixos e validados a cada request. | Escopo | Permissão | | ------- | -------------------------------------------------------------------------------------- | | `read` | Listar e consultar recursos (`GET`) | | `write` | Criar, atualizar e desativar recursos (`POST`, `DELETE`) | | `admin` | Operações críticas (ex: gerenciar chaves via API). Não exposto no dashboard atualmente | Os escopos são **hierárquicos**: um nível maior satisfaz a exigência de um menor. ```text theme={} read ⊂ write ⊂ admin ``` Ou seja: um endpoint que exige `read` aceita também chaves com `write` ou `admin`; um endpoint que exige `write` aceita `write` ou `admin`. Siga o **princípio do menor privilégio**: crie chaves `read` quando a integração só consulta dados, e reserve `write` para onde realmente precisa criar ou modificar. ## Obtendo uma chave Só papéis **owner** e **admin** da organização têm acesso ao menu de chaves. Membros comuns não. No dashboard da Chargefy, em `dashboard.chargefy.io`. Clique em **Nova chave**, dê um nome descritivo ("Produção", "Integração X") e escolha os escopos. Ele aparece **uma vez só**. Guarde em secret manager ou variável de ambiente antes de fechar a tela. O ciclo de vida completo (criar, listar, revogar, expirar, rotacionar) está em [Gerenciar api keys](/integrate/api-keys). ## Rotação e revogação * **Revogação instantânea** — na lista de chaves, clique em **Revogar**. Requests com aquele token passam a retornar `401` em milissegundos. * **Rotação** — não há "rotate in-place". O fluxo de zero downtime é: criar a chave nova → atualizar a aplicação → confirmar pelo "último uso" → revogar a antiga. * **Último uso** — a Chargefy registra o `last_used_at` de cada chave. Chaves paradas há muito tempo são candidatas a revoke preventivo. ## Respostas de autenticação Toda falha segue o [envelope de erro público](/api-reference/introduction): `{ "error": { "code", "message", "type" } }`, com chaves na ordem canônica. ### Credencial ausente ou inválida — `401` Token não enviado, com formato errado, revogado, expirado ou que não bate com nenhuma chave. ```json theme={} { "error": { "code": "unauthorized", "message": "Missing or invalid API key.", "type": "authentication_error" } } ``` ### Escopo insuficiente — `403` A chave é válida, mas não tem o escopo que o endpoint exige. ```json theme={} { "error": { "code": "permission_denied", "message": "The API key does not have the required scope.", "type": "invalid_request_error" } } ``` ### Organização inacessível — `403` A chave de plataforma apontou um `Organization` que não é uma organização conectada ativa. ```json theme={} { "error": { "code": "permission_denied", "message": "The API key cannot access the requested organization.", "type": "invalid_request_error" } } ``` As mensagens (`message`) saem em inglês por padrão e servem para log do desenvolvedor. Faça branching de UX pelo `code`, não pela string da mensagem. ## Por que a base é `api.chargefy.io` Sempre faça suas chamadas autenticadas por API key contra `https://api.chargefy.io/v1`. Esse host é o ponto de entrada oficial: ele aplica rate limiting, rastreamento de request e proteções de borda antes de a requisição chegar ao backend. Requisições com API key que **não passam por `api.chargefy.io`** são rejeitadas com `401`. O backend exige a assinatura de borda que só esse host adiciona — não tente chamar URLs internas de função diretamente. ## Segurança * **Nunca** exponha API keys em código client-side (browser, mobile). Toda chamada autenticada por API key é server-side. * Armazene em secret manager ou variável de ambiente (`CHARGEFY_API_KEY`), nunca em código-fonte versionado nem em log. * Use sempre o **menor escopo** necessário, e separe `live` de `test`. * Revogue imediatamente qualquer chave comprometida (vazamento em log, commit, laptop roubado). A revogação é instantânea — não há janela de uso do token antigo. ## E o token do dashboard? Quando você usa o painel em `dashboard.chargefy.io`, a UI autentica com um **token de sessão de usuário** (JWT) que ela mesma gerencia, e o acesso aos dados é gateado por papel (`owner`/`admin`/`member`) e pelas regras de cada organização. Esse caminho é interno da interface: **você não emite nem cola esse token em integrações**. Para qualquer código server-to-server, o caminho é a API key descrita acima. ## Próximos passos Criar, listar, revogar e expirar chaves no dashboard. Base URL, paginação, envelope de erro e convenções. O contrato de auth no nível da referência. Verificar assinaturas e tratar retries.