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

# Chaves de API

> Aprenda como funcionam as chaves de API e como utilizá-las para acessar a Alpa

<Tip>
  A **chave de API** é sua credencial de acesso à Alpa. Ela identifica sua conta e autoriza cada requisição enviada para a nossa API. **Sem uma chave válida, nenhum pedido será aceito.**
</Tip>

## O que você pode fazer com suas chaves

As chaves de API são gerenciadas diretamente pelo Dashboard. Com elas, você pode:

* Ver todas as chaves ativas
* Criar novas chaves para diferentes projetos ou integrações
* Revogar chaves comprometidas ou que não são mais usadas

<Card title="Desenvolvimento x Produção" horizontal>
  Todas as requisições usam o mesmo endpoint `https://alpa-sistema-api.onrender.com`.
  O ambiente é definido **pela chave utilizada**:

  * Chaves criadas em **Desenvolvimento** → transações simuladas
  * Chaves criadas em **Produção** → transações reais
</Card>

<Card title="Erro de Autenticação (401)" horizontal>
  Você receberá um **HTTP 401** quando:

  * A chave não for enviada no header
  * A chave estiver incorreta ou mal formatada
  * A chave tiver sido revogada
</Card>

## Permissões da chave de API

A chave define **quais recursos** você pode acessar. Endpoints sem a permissão correspondente retornam **403 Forbidden**.

### Permissões disponíveis

| Recurso            | Permissões                                |
| ------------------ | ----------------------------------------- |
| Links de Pagamento | `paymentLinks:read`, `paymentLinks:write` |
| Transações         | `transactions:read`, `transactions:write` |
| Produtos           | `products:read`, `products:write`         |
| Clientes           | `customers:read`, `customers:write`       |
| Cupons             | `coupons:read`, `coupons:write`           |
| Webhooks           | `webhooks:read`, `webhooks:write`         |
| Saques             | `withdrawals:read`, `withdrawals:write`   |

## Boas práticas de segurança

<Card horizontal>
  * Armazene suas chaves em variáveis de ambiente — nunca no código-fonte
  * Nunca publique sua chave em repositórios públicos ou grupos
  * A Alpa **nunca** solicitará sua chave por e-mail ou chat
  * Revogue imediatamente qualquer chave que possa ter vazado
  * Use chaves diferentes para desenvolvimento e produção
</Card>

***

## Como criar uma chave de API

<Steps>
  <Step title="Acesse o Dashboard">
    Faça login em [app.usealpa.com](https://app.usealpa.com) e navegue até **Configurações → Credenciais de API**.
  </Step>

  <Step title="Crie uma nova chave">
    Clique em **"Criar Nova API Key"**, dê um nome descritivo (ex: "Integração Produção") e selecione as permissões necessárias.
  </Step>

  <Step title="Copie a chave gerada">
    Copie a chave imediatamente e salve em um local seguro ou gerenciador de segredos. **Ela não será exibida novamente.**
  </Step>
</Steps>

***

## Usando sua chave

Inclua a chave no header `Authorization` de todas as requisições:

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/payment-links" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json"
```

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/payment-links', {
    headers: {
      'Authorization': `Bearer ${process.env.ALPA_API_KEY}`,
      'Content-Type': 'application/json',
    },
  });
  ```

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

  response = requests.get(
      'https://alpa-sistema-api.onrender.com/api/v1/payment-links',
      headers={'Authorization': f'Bearer {os.getenv("ALPA_API_KEY")}'},
  )
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://alpa-sistema-api.onrender.com/api/v1/payment-links');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer ' . $_ENV['ALPA_API_KEY'],
  ]);
  ```
</CodeGroup>

<Card title="Nota importante">
  O mesmo endpoint é usado para desenvolvimento e produção. O ambiente é determinado automaticamente pela chave de API utilizada na requisição.
</Card>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Início rápido" icon="rocket" href="./quickstart">
    Faça sua primeira requisição em minutos.
  </Card>

  <Card title="Criar link de pagamento" icon="link" href="../payment-links/create">
    Gere seu primeiro link de checkout.
  </Card>

  <Card title="Webhooks" icon="bell" href="../webhooks/reference">
    Configure notificações automáticas de eventos.
  </Card>

  <Card title="SDKs" icon="boxes-stacked" href="../sdks">
    Use nossas bibliotecas oficiais para integrar mais rápido.
  </Card>
</CardGroup>