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

# Autenticação

> Configure suas chaves de API para acessar os endpoints da Garu

## Métodos de Autenticação

A API da Garu suporta dois métodos de autenticação:

| Método           | Formato do Header                            | Caso de Uso                        |
| ---------------- | -------------------------------------------- | ---------------------------------- |
| **Chave de API** | `Bearer sk_live_xxx` ou `Bearer sk_test_xxx` | Integrações servidor-para-servidor |
| **Token JWT**    | `Bearer eyJhbG...`                           | Dashboard e aplicações frontend    |

<Note>
  Para integrações de API, recomendamos usar **Chaves de API** por serem mais simples e seguras para comunicação entre servidores.
</Note>

## Obtendo sua Chave de API

<Steps>
  <Step title="Acesse o Dashboard">
    Faça login no [Dashboard da Garu](https://garu.com.br/inicio)
  </Step>

  <Step title="Navegue até Desenvolvedores">
    Vá para **Configurações** → **Desenvolvedores**
  </Step>

  <Step title="Crie uma nova chave">
    Clique em **Criar chave de API**
  </Step>

  <Step title="Selecione o ambiente">
    Escolha o tipo de chave:

    * `sk_test_` - Para desenvolvimento e testes (sem cobranças reais)
    * `sk_live_` - Para produção (processa pagamentos reais)
  </Step>

  <Step title="Salve sua chave">
    **Importante:** Salve a chave imediatamente. Ela só será exibida uma vez!
  </Step>
</Steps>

## Usando sua Chave de API

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

```bash theme={null}
curl -X GET https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_abc123xyz..."
```

### Exemplos por Linguagem

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://garu.com.br/api/products', {
    headers: {
      'Authorization': `Bearer ${process.env.GARU_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  ```

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

  headers = {
      'Authorization': f'Bearer {os.environ["GARU_API_KEY"]}',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://garu.com.br/api/products',
      headers=headers
  )
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = getenv('GARU_API_KEY');

  $ch = curl_init('https://garu.com.br/api/products');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer {$apiKey}",
          'Content-Type: application/json'
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);
  ```
</CodeGroup>

## Ambientes

| Ambiente     | Prefixo da Chave | Descrição                                               |
| ------------ | ---------------- | ------------------------------------------------------- |
| **Sandbox**  | `sk_test_`       | Ambiente de testes. Nenhuma cobrança real é processada. |
| **Produção** | `sk_live_`       | Ambiente de produção. Processa pagamentos reais.        |

<Warning>
  **Nunca** use chaves `sk_live_` em ambientes de desenvolvimento ou testes. Cobranças reais serão processadas!
</Warning>

## Boas Práticas de Segurança

<AccordionGroup>
  <Accordion title="Nunca exponha chaves no código cliente">
    Chaves de API devem ser usadas apenas em código servidor. Nunca inclua chaves em JavaScript frontend, aplicativos móveis ou repositórios públicos.
  </Accordion>

  <Accordion title="Use variáveis de ambiente">
    Armazene suas chaves em variáveis de ambiente, não diretamente no código:

    ```bash theme={null}
    # .env
    GARU_API_KEY=sk_test_abc123xyz...
    ```
  </Accordion>

  <Accordion title="Use chaves diferentes por ambiente">
    Crie chaves separadas para desenvolvimento, staging e produção. Isso facilita a rotação e auditoria.
  </Accordion>

  <Accordion title="Rotacione chaves comprometidas">
    Se uma chave for exposta, revogue-a imediatamente no Dashboard e crie uma nova.
  </Accordion>

  <Accordion title="Implemente rate limiting">
    A API tem limite de 100 requisições por minuto. Implemente backoff exponencial para lidar com erros 429.
  </Accordion>
</AccordionGroup>

## Erros de Autenticação

### 401 Unauthorized

```json theme={null}
{
  "statusCode": 401,
  "message": "API key is required"
}
```

**Causas comuns:**

* Header `Authorization` ausente
* Prefixo `Bearer` faltando
* Chave de API inválida ou expirada

**Solução:** Verifique se o header está no formato correto: `Authorization: Bearer sk_xxx`

### 403 Forbidden

```json theme={null}
{
  "statusCode": 403,
  "message": "Insufficient permissions"
}
```

**Causas comuns:**

* Chave de API não tem permissão para o endpoint
* Tentando acessar recursos de outro vendedor

**Solução:** Verifique as permissões da sua chave no Dashboard.

## Testando sua Autenticação

Use este comando para verificar se sua chave está funcionando:

```bash theme={null}
curl -X GET https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_sua_chave_api" \
  -w "\nHTTP Status: %{http_code}\n"
```

<Check>
  Se você receber HTTP Status 200, sua autenticação está configurada corretamente!
</Check>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Produtos" icon="box" href="/api-reference/produtos/criar">
    Aprenda a criar seu primeiro produto
  </Card>

  <Card title="Link de Pagamento" icon="link" href="/api-reference/produtos/link-pagamento">
    Obtenha o link para receber pagamentos
  </Card>
</CardGroup>