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

# Autenticação

> Aprenda a autenticar suas requisições na Oxenty API

A Oxenty API utiliza **API Key** para autenticação em integrações. Todas as requisições devem incluir a chave no header `X-API-Key`.

## API Key

API Keys são chaves de longa duração (até serem revogadas) ideais para integrações backend-to-backend.

### Gerando uma API Key

1. Acesse o **Dashboard** da Oxenty
2. Navegue até\*\*→ API Keys\*\*
3. Clique em **"Criar Nova Key"**
4. Defina um nome identificador e as permissões
5. Copie e armazene a key em local seguro

<Warning>
  A API Key completa é exibida apenas uma vez. Armazene-a em um local seguro (como variáveis de ambiente ou secrets manager).
</Warning>

### Usando API Key

```bash theme={"system"}
curl -X GET "https://api.oxenty.api.br/api/sessions" \
  -H "X-API-Key: oxt_sk_1234567890abcdef..."
```

<Info>
  API Keys começam com o prefixo `oxt_sk_` para fácil identificação.
</Info>

***

## Exemplo Completo

<CodeGroup>
  ```typescript TypeScript SDK theme={"system"}
  import { OxentyClient } from 'oxenty-sdk';

  // Com API Key (recomendado para backend)
  const client = new OxentyClient({
    baseUrl: 'https://api.oxenty.api.br',
    apiKey: process.env.OXENTY_API_KEY,
  });

  // Listar sessões
  const sessions = await client.sessions.list();
  ```

  ```typescript TypeScript Fetch theme={"system"}
  const API_KEY = process.env.OXENTY_API_KEY;

  async function getSessions() {
    const response = await fetch('https://api.oxenty.api.br/api/sessions', {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
      },
    });
    
    return response.json();
  }
  ```

  ```python Python theme={"system"}
  import os
  import requests

  API_KEY = os.environ.get('OXENTY_API_KEY')

  headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
  }

  response = requests.get(
    'https://api.oxenty.api.br/api/sessions',
    headers=headers
  )

  sessions = response.json()
  ```
</CodeGroup>

***

## Boas Práticas

<AccordionGroup>
  <Accordion title="Nunca exponha tokens no frontend" icon="shield">
    API Keys devem ser usadas apenas no backend. Para aplicações frontend, implemente um proxy no seu servidor.
  </Accordion>

  <Accordion title="Rotacione keys regularmente" icon="refresh-cw">
    Crie novas API Keys periodicamente e revogue as antigas. Isso minimiza riscos caso uma key seja comprometida.
  </Accordion>

  <Accordion title="Use variáveis de ambiente" icon="eye-off">
    Nunca commit tokens no código. Use `.env` files, secrets managers ou variáveis de ambiente do seu provedor cloud.
  </Accordion>

  <Accordion title="Minimize permissões" icon="list-checks">
    Ao criar API Keys, conceda apenas as permissões necessárias para a integração específica.
  </Accordion>
</AccordionGroup>

***

## Erros de Autenticação

| Código | Mensagem          | Descrição                                       |
| ------ | ----------------- | ----------------------------------------------- |
| 401    | `UNAUTHORIZED`    | Token ausente ou inválido                       |
| 403    | `FORBIDDEN`       | API Key válida mas sem permissão para o recurso |
| 403    | `API_KEY_REVOKED` | API Key foi revogada                            |

<Note>
  Veja a página de [Erros](/errors) para mais detalhes sobre tratamento de erros.
</Note>