Chaves de API

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

Base URL

https://api.shappire.tools/v1

Desenvolvimento local: http://localhost:8080/v1Todas 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_.

Tutorial visual: Criar chave de API. Fluxo completo: Primeira integração.

API keys são credenciais secretasTrate 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

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 · Boas práticas

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

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

export SHAPPIRE_API_KEY=shp_live_SUA_CHAVE

Enviar na requisição

Recomendado — header X-API-Key:

curl https://api.shappire.tools/v1/platforms \
  -H "X-API-Key: $SHAPPIRE_API_KEY"

Alternativa — Authorization: Bearer (compatibilidade):

curl https://api.shappire.tools/v1/platforms \
  -H "Authorization: Bearer $SHAPPIRE_API_KEY"

Em código backend:

const apiKey = process.env.SHAPPIRE_API_KEY;

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.

Rotacionar chave

Crie nova chave com mesmos escopos
Atualize variáveis de ambiente nos serviços
Teste resolve + download
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 · Rotas da API · Boas práticas

Começar

Integração

Exemplos de código

Tutoriais

Referência

Arquitetura correta

Arquitetura incorreta

Onde armazenar

Prefixos por ambiente

Criar a chave

Enviar na requisição

Erros de autenticação

Permissões (escopos)

Rotacionar chave

Boas práticas

Documentação das rotas

​Arquitetura correta

​Arquitetura incorreta

​Onde armazenar

​Prefixos por ambiente

​Criar a chave

​Enviar na requisição

​Erros de autenticação

​Permissões (escopos)

​Rotacionar chave

​Boas práticas

​Documentação das rotas

Arquitetura correta

Arquitetura incorreta

Onde armazenar

Prefixos por ambiente

Criar a chave

Enviar na requisição

Erros de autenticação

Permissões (escopos)

Rotacionar chave

Boas práticas

Documentação das rotas