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

# Autenticação

> Como autenticar suas requisições com o par de tokens público e secreto

Toda requisição à API pública é autenticada com **HTTP Basic Auth** usando um par de tokens:

| Token         | Prefixo  | Papel no Basic Auth                      |
| ------------- | -------- | ---------------------------------------- |
| Token público | `pb_...` | *username* — identifica a credencial     |
| Token secreto | `sk_...` | *password* — prova a posse da credencial |

O header enviado é:

```text theme={null}
Authorization: Basic base64(pb_xxx:sk_xxx)
```

A conta (cliente) é determinada pela credencial — não há parâmetro de conta nas rotas.

## Exemplos

<CodeGroup>
  ```bash curl theme={null}
  curl -u "pb_SEU_TOKEN_PUBLICO:sk_SEU_TOKEN_SECRETO" \
    "https://api.sortify.com.br/v1/raffles"
  ```

  ```javascript Node.js theme={null}
  const credentials = Buffer.from(
    `${process.env.SORTIFY_PUBLIC_TOKEN}:${process.env.SORTIFY_SECRET_TOKEN}`
  ).toString("base64");

  const response = await fetch("https://api.sortify.com.br/v1/raffles", {
    headers: { Authorization: `Basic ${credentials}` },
  });

  const { data } = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api.sortify.com.br/v1/raffles",
      auth=(os.environ["SORTIFY_PUBLIC_TOKEN"], os.environ["SORTIFY_SECRET_TOKEN"]),
  )

  data = response.json()["data"]
  ```
</CodeGroup>

## Obtendo credenciais

As credenciais são criadas no [painel da Sortify](https://app.sortify.com.br). Cada conta pode ter **múltiplas credenciais nomeadas** (por exemplo, "produção" e "homologação"), revogáveis individualmente.

<Warning>
  O token secreto é exibido **somente no momento da criação**. Ele é armazenado de forma irreversível (hash) e não pode ser recuperado depois. Se você perdê-lo, crie uma nova credencial e revogue a antiga.
</Warning>

## Boas práticas

* Guarde os tokens em variáveis de ambiente ou em um gerenciador de segredos — nunca no código-fonte.
* Use uma credencial por ambiente/integração. Assim, revogar uma não derruba as demais.
* Monitore o campo `last_used_at` no painel para identificar credenciais em desuso.

## Rotação de tokens

Para rotacionar credenciais sem interrupção:

<Steps>
  <Step title="Crie uma nova credencial">
    No painel, crie a credencial substituta e copie o novo par de tokens.
  </Step>

  <Step title="Atualize sua integração">
    Troque o par de tokens na sua aplicação e confirme que as requisições seguem funcionando.
  </Step>

  <Step title="Revogue a credencial antiga">
    A revogação tem efeito **imediato**: a próxima requisição com a credencial revogada é rejeitada.
  </Step>
</Steps>

## Erros de autenticação

| HTTP  | Código                    | Quando ocorre                                                           |
| ----- | ------------------------- | ----------------------------------------------------------------------- |
| `401` | `API_CREDENTIALS_MISSING` | Header `Authorization` ausente                                          |
| `401` | `INVALID_API_CREDENTIALS` | Formato inválido, token público desconhecido ou token secreto incorreto |
| `401` | `API_CREDENTIAL_REVOKED`  | Credencial revogada                                                     |
| `403` | `ACCOUNT_INACTIVE`        | Conta desativada na plataforma                                          |
| `429` | `RATE_LIMIT_EXCEEDED`     | Mais de 120 requisições por minuto com a mesma credencial               |

<Note>
  A API não envia o header `WWW-Authenticate` em respostas `401` — isso evita o pop-up de login em navegadores. Clientes HTTP gerados automaticamente que dependem desse header devem tratar o `401` diretamente.
</Note>