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

# Autenticação

> Como gerar e usar sua API key com segurança

## Gerar uma API key

1. Acesse a plataforma Cordialy
2. Vá em **Integrações → API Keys**
3. Clique em **Nova chave**
4. Dê um nome descritivo (ex: `producao-crm`, `erp-interno`)
5. Copie a chave gerada — ela só aparece uma vez

<Warning>
  Guarde a chave em um local seguro imediatamente. Após fechar o modal, não é possível visualizá-la novamente. Se perder, crie uma nova.
</Warning>

## Usar a API key

Inclua a chave no header `X-API-Key` em todas as requisições:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cordialy.ai/integrations/v1/leads \
    -H "X-API-Key: cord_live_xxxxxxxxxxxx"
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cordialy.ai/integrations/v1/leads', {
    headers: {
      'X-API-Key': process.env.CORDIALY_API_KEY,
    },
  });
  ```

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

  response = requests.get(
      'https://api.cordialy.ai/integrations/v1/leads',
      headers={'X-API-Key': os.environ['CORDIALY_API_KEY']}
  )
  ```

  ```php PHP theme={null}
  $response = Http::withHeaders([
      'X-API-Key' => env('CORDIALY_API_KEY'),
  ])->get('https://api.cordialy.ai/integrations/v1/leads');
  ```
</CodeGroup>

## Erros de autenticação

| Código | Mensagem                              | Causa                               |
| ------ | ------------------------------------- | ----------------------------------- |
| `401`  | `API key inválida`                    | Chave incorreta ou revogada         |
| `401`  | `API key não encontrada`              | Header `X-API-Key` ausente          |
| `403`  | `Recurso não disponível no seu plano` | Endpoint não incluso no plano atual |
| `429`  | `Limite de requisições atingido`      | Muitas requisições em pouco tempo   |

## Boas práticas de segurança

<AccordionGroup>
  <Accordion title="Nunca exponha a chave no frontend">
    API keys devem ficar apenas no backend. Se exposta no código do browser, qualquer pessoa pode usá-la para enviar mensagens ou acessar seus dados.
  </Accordion>

  <Accordion title="Use variáveis de ambiente">
    Nunca commite a chave no código-fonte. Use `.env` em desenvolvimento e variáveis de ambiente seguras em produção (AWS Secrets Manager, Vercel Env, Railway Variables, etc.).
  </Accordion>

  <Accordion title="Crie chaves separadas por ambiente">
    Use chaves diferentes para `desenvolvimento`, `staging` e `produção`. Assim você pode revogar uma sem afetar as outras.
  </Accordion>

  <Accordion title="Revogue chaves que não usa mais">
    Se um sistema foi descontinuado ou uma chave foi exposta acidentalmente, revogue imediatamente em **Integrações → API Keys**.
  </Accordion>
</AccordionGroup>

## Múltiplas chaves

Você pode ter várias chaves ativas ao mesmo tempo — útil para integrar diferentes sistemas (CRM, ERP, e-commerce) com controle individual. Cada chave pode ser revogada sem afetar as demais.