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

# Autenticação

> Como autenticar suas requisições na API do Talk AI.

## API Keys

Todas as requisições à API do Talk AI são autenticadas via **API key**. Chaves são geradas no [Dashboard](https://talk.saninternet.com) e associadas a uma empresa.

### Formato da chave

```
pyp_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4
```

Todas as chaves começam com o prefixo `pyp_live_` seguido de 48 caracteres hexadecimais.

### Enviando a chave

Inclua sua API key no header `Authorization` de todas as requisições:

```bash theme={null}
curl -X GET https://api-talk.saninternet.com/v1/api/status \
  -H "Authorization: Bearer pyp_live_SUA_API_KEY"
```

<Warning>
  Nunca exponha sua API key em código frontend, repositórios públicos ou logs. Trate-a como uma senha.
</Warning>

## Segurança

* As chaves são armazenadas como hash SHA-256 no servidor, nunca em texto puro
* Cada chave é associada a uma única empresa
* Todas as requisições são logadas com IP, user-agent e timestamp
* Chaves podem ser revogadas a qualquer momento no Dashboard

## Validação de assinatura

Além da chave ser válida, a API verifica se a **assinatura da empresa está ativa**. Empresas com assinatura inativa recebem:

```json theme={null}
{
  "statusCode": 403,
  "error": "SubscriptionInactive",
  "message": "Sua assinatura não está ativa",
  "subscriptionStatus": "CANCELLED"
}
```

## Erros de autenticação

| Código | Erro                         | Causa                                              |
| ------ | ---------------------------- | -------------------------------------------------- |
| `401`  | `Missing API key`            | Header `Authorization` ausente                     |
| `401`  | `Invalid API key format`     | Formato incorreto (deve ser `Bearer pyp_live_...`) |
| `401`  | `Invalid or expired API key` | Chave inexistente ou revogada                      |
| `403`  | `SubscriptionInactive`       | Assinatura da empresa inativa                      |

## Boas práticas

<AccordionGroup>
  <Accordion title="Use variáveis de ambiente">
    Nunca coloque a API key diretamente no código. Use variáveis de ambiente:

    ```bash theme={null}
    export SANTALK_API_KEY="pyp_live_SUA_API_KEY"
    ```

    ```javascript theme={null}
    const apiKey = process.env.SANTALK_API_KEY;
    ```
  </Accordion>

  <Accordion title="Rotacione chaves periodicamente">
    Crie uma nova chave no Dashboard, atualize seus sistemas e revogue a chave antiga.
  </Accordion>

  <Accordion title="Use chaves diferentes por ambiente">
    Mantenha chaves separadas para desenvolvimento, staging e produção.
  </Accordion>
</AccordionGroup>