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

# Autenticação

> API keys por organização, enviadas como Bearer token

A API da iuzypay é autenticada por **API keys**. Cada chave pertence a uma organização: toda chamada feita com ela lê e escreve apenas os dados daquela organização.

## Formato e envio

As chaves têm o prefixo `iuzy_sk_` e são enviadas no header `Authorization`:

```bash theme={null}
curl https://api.iuzypay.com/v1/me \
  -H "Authorization: Bearer iuzy_sk_..."
```

## Criar e revogar chaves

As chaves são gerenciadas no dashboard, em **Configurações → API keys** (requer a permissão `api_keys:write`):

* **Criar** — a chave completa aparece uma única vez, na criação. A iuzypay guarda apenas um hash SHA-256; não há como recuperar o valor depois.
* **Revogar** — uma chave revogada é rejeitada imediatamente. Se suspeitar de vazamento, revogue e crie outra na hora; você pode manter mais de uma chave ativa para fazer a troca sem downtime.

## Erros de autenticação

Sem uma chave válida, a API responde `401` com o [envelope de erro padrão](/api/convencoes#erros):

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}
```

| Situação                                              | Mensagem                       |
| ----------------------------------------------------- | ------------------------------ |
| Header ausente ou chave fora do formato `iuzy_sk_...` | `missing or malformed API key` |
| Chave inexistente ou revogada                         | `invalid or revoked API key`   |

## Boas práticas

<Warning>
  A API key dá acesso total à API em nome da sua organização. Use-a **somente no servidor** — nunca em código que roda no navegador ou em apps distribuídos.
</Warning>

* Guarde a chave em variável de ambiente ou gerenciador de segredos, nunca no repositório.
* Crie uma chave por sistema (ex.: `erp`, `automacao-email`) — revogar uma não derruba as outras e o nome identifica a origem.
* Rotacione periodicamente: crie a chave nova, troque no sistema e revogue a antiga.