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

# Chaves de API

> Criar, rotacionar e proteger shp_live_ — header X-API-Key e escopos

Chaves de API autenticam integrações **server-to-server**. Não usam sessão do dashboard.

<Info>
  **Base URL**

  ```
  https://api.shappire.tools/v1
  ```

  Desenvolvimento local: `http://localhost:8080/v1`

  Todas as rotas da API pública usam esse prefixo. Chaves de produção usam o prefixo `shp_live_`; em ambiente local (não-produção), o prefixo é `shp_test_`.
</Info>

Tutorial visual: [Criar chave de API](/tutorials/api-key). Fluxo completo: [Primeira integração](/pages/guides/primeira-integracao).

<Danger>
  **API keys são credenciais secretas**

  Trate `shp_live_...` como senha de banco de dados. Qualquer pessoa com a chave pode consumir sua cota e enfileirar downloads no seu projeto.

  **Nunca:**

  * commite no Git (`.env` no `.gitignore`)
  * coloque em código frontend (React, Vue, Svelte, Next.js client components)
  * envie em apps mobile sem proxy backend
  * armazene em `localStorage`, `sessionStorage` ou cookies do browser
  * exponha em URLs, query strings ou repositórios públicos
</Danger>

## Arquitetura correta

```
Browser / App
      ↓
Backend do cliente (seu servidor)
      ↓  X-API-Key: shp_live_... (variável de ambiente)
Shappire API
```

O usuário final **nunca** vê a chave. Seu backend valida a sessão do usuário e chama a Shappire server-to-server.

## Arquitetura incorreta

```
Browser / App
      ↓  X-API-Key: shp_live_... (hardcoded ou em bundle JS)
Shappire API
```

Qualquer usuário pode abrir DevTools → Network, copiar a chave e usar fora do seu controle.

## Onde armazenar

| Ambiente                | Recomendação                                  |
| ----------------------- | --------------------------------------------- |
| Servidor Node/Python/Go | `process.env.SHAPPIRE_API_KEY` / `os.environ` |
| Docker / K8s            | Secret do orchestrator                        |
| CI/CD                   | Secret do pipeline (GitHub Actions, etc.)     |
| Local                   | `.env` (nunca commitado)                      |

Veja também: [Chaves de API](/pages/guides/authentication) · [Boas práticas](/pages/guides/boas-praticas)

## Prefixos por ambiente

| Ambiente                         | Prefixo     | Exemplo              |
| -------------------------------- | ----------- | -------------------- |
| Produção (`NODE_ENV=production`) | `shp_live_` | `shp_live_abc123...` |
| Local / desenvolvimento          | `shp_test_` | `shp_test_abc123...` |

O secret completo aparece **uma vez** na criação. O servidor armazena apenas o hash — não é possível recuperar depois.

## Criar a chave

[Developer → Projetos → API Keys](https://shappire.tools/developer/projects)

| Campo   | Descrição                                     |
| ------- | --------------------------------------------- |
| Nome    | Identifique o sistema (ex. `Worker Produção`) |
| Escopos | `media:resolve`, `media:download` ou ambos    |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
export SHAPPIRE_API_KEY=shp_live_SUA_CHAVE
```

## Enviar na requisição

**Recomendado** — header `X-API-Key`:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/platforms \
  -H "X-API-Key: $SHAPPIRE_API_KEY"
```

**Alternativa** — `Authorization: Bearer` (compatibilidade):

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/platforms \
  -H "Authorization: Bearer $SHAPPIRE_API_KEY"
```

Em código backend:

```javascript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
const apiKey = process.env.SHAPPIRE_API_KEY;
```

```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
import os
api_key = os.environ["SHAPPIRE_API_KEY"]
```

## Erros de autenticação

| Código            | HTTP | Causa                                                  |
| ----------------- | ---- | ------------------------------------------------------ |
| `invalid_api_key` | 401  | Chave ausente, formato inválido ou hash não encontrado |
| `revoked_api_key` | 401  | Chave revogada no dashboard                            |
| `forbidden`       | 403  | Escopo insuficiente ou projeto inativo                 |

## Permissões (escopos)

| Escopo           | Rota                   |
| ---------------- | ---------------------- |
| `media:resolve`  | `POST /media/resolve`  |
| `media:download` | `POST /media/download` |

Rotas sem escopo explícito exigem apenas chave válida: `GET /platforms`, `GET /jobs/{jobId}`.

Lista completa: [Permissões da API key](/pages/guides/api-permissions).

## Rotacionar chave

1. Crie nova chave com mesmos escopos
2. Atualize variáveis de ambiente nos serviços
3. Teste resolve + download
4. Revogue a chave antiga no dashboard

## Boas práticas

* Uma chave por ambiente/serviço
* Nunca exponha em frontend, mobile ou repositórios
* Mascare em logs: `shp_live_...abc1`
* Monitore uso no dashboard para detectar anomalias
* Princípio do menor privilégio: só os escopos necessários

## Documentação das rotas

[API Reference](/api-reference/overview) · [Rotas da API](/api-reference/escopo-api-publica) · [Boas práticas](/pages/guides/boas-praticas)