> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Chave secreta no header, escopos por endpoint e a diferença entre 401 e 403.

Toda chamada leva a chave no header:

```bash theme={null}
curl https://api.usevext.com/v1/balance \
  -H "Authorization: Bearer sk_live_..."
```

Toda chamada vai para:

```
https://api.usevext.com
```

Todo endpoint desta versão vive sob `/v1`. A URL completa de uma criação de cobrança é
`https://api.usevext.com/v1/charges`.

## A chave aparece uma única vez

A chave é criada em **Desenvolvedores** no painel, e o valor em claro aparece **uma única vez**, na
criação. Guardamos apenas um hash SHA-256.

Nem o suporte consegue recuperá-la, e é esse o ponto: um dump do nosso banco não permite cobrar em
nome de ninguém. Perdeu, gere outra e revogue a anterior.

<Warning>
  Guarde a chave no **servidor**, nunca no JavaScript que chega ao navegador. Qualquer pessoa que
  abra as ferramentas de desenvolvedor da página consegue lê-la de lá, e a chave dá acesso às suas
  cobranças, aos seus estornos e ao seu saldo.
</Warning>

## Ambientes

Chaves de teste usam o prefixo `sk_test_`; as de produção, `sk_live_`. A diferença é visível a olho
nu de propósito — uma chave de teste colada em produção precisa ser reconhecível antes de alguém
passar a tarde investigando por que nada acontece.

## Escopos

Cada chave carrega escopos. Dê a cada integração só o que ela usa: uma chave de relatório que
vazou não deveria conseguir criar cobrança nem estornar.

| Escopo          | Libera                                       |
| --------------- | -------------------------------------------- |
| `charges:write` | `POST /v1/charges`                           |
| `charges:read`  | `GET /v1/charges` e `GET /v1/charges/{code}` |
| `refunds:write` | `POST /v1/charges/{code}/refund`             |
| `balance:read`  | `GET /v1/balance`                            |

## 401 e 403 respondem coisas diferentes

Chamar um endpoint fora do escopo devolve `403`, e não `401`: a chave está certa, faltou permissão.
Devolver `401` diria "sua chave está errada" a quem tem a chave certa, e a pessoa iria procurar o
problema no lugar errado.

**`401` — o problema é a chave.** Quatro códigos, distinguidos na `message` e nunca no status:

| `code`            | Significa                       |
| ----------------- | ------------------------------- |
| `missing_api_key` | Você não enviou o header        |
| `invalid_api_key` | A chave não existe              |
| `revoked_api_key` | A chave existiu e foi desligada |
| `expired_api_key` | A chave existiu e venceu        |

A revogada é distinguida da inexistente na mensagem porque quem integra precisa saber que a chave
existiu e foi desligada — e quem está adivinhando tokens não aprende nada com isso, já que o status
é o mesmo nos quatro casos.

**`403` — o problema é o escopo.** O `details` diz exatamente o que faltou:

```json insufficient_scope theme={null}
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "Esta chave não tem o escopo [refunds:write].",
    "details": {
      "required_ability": "refunds:write",
      "abilities": ["charges:read", "charges:write"]
    }
  }
}
```

Nenhum dos dois se resolve repetindo a chamada. Corrija a chave, ou gere outra com o escopo certo.

## Veja também

<CardGroup cols={2}>
  <Card title="Erros" icon="triangle-alert" href="/essenciais/erros">
    O catálogo completo e o que fazer em cada família.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/assinatura">
    O segredo de assinatura é outro, e por endpoint.
  </Card>
</CardGroup>

***

Ficou algo de fora? Escreva para [suporte@usevext.com](mailto:suporte@usevext.com). Se o assunto for
uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o
`X-Vext-Delivery` — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.