Autenticação

Todas as requisições à API (exceto /v1/health) exigem uma API key válida enviada via header HTTP.

Formato da API key

As API keys da GDREdu seguem o formato:

gdredu_live_<64 caracteres hexadecimais>

Exemplo:

gdredu_live_3f8a9b2c1e7d4f6a5b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a

:::caution
A API key é um segredo. Trate-a como uma senha — nunca a exponha em código-fonte público, repositórios Git, logs ou URLs visíveis no navegador.
:::

Como enviar a API key

Há duas formas equivalentes:

Header Authorization (recomendado)

Authorization: Bearer gdredu_live_sua_api_key

Header x-api-key

x-api-key: gdredu_live_sua_api_key

Ambos os métodos são aceitos em todos os endpoints. Recomendamos Authorization: Bearer por ser o padrão da indústria.

Como obter uma API key

API keys são gerenciadas por administradores no painel GDREdu:

1. Um administrador da instituição acessa Dashboard → API Keys.
2. Clica em "Criar API Key".
3. Define:
   • Nome: identificação interna (ex: "Integração ERP", "App Mobile")
   • Escopo: Business (toda a instituição) ou Branch (uma escola específica)
   • Scopes: permissões granulares (ex: students:read, series:write)
   • Expiração (opcional): data em que a key deixa de funcionar
   • Rate limit (opcional): requisições por minuto (padrão: 100)
4. O segredo completo (gdredu_live_...) é mostrado apenas uma vez no momento da criação.
5. O administrador deve copiá-lo e armazená-lo em um local seguro (cofre de senhas, variável de ambiente, etc.).

:::warning
O segredo completo da API key não pode ser recuperado após a criação. Apenas um prefixo (ex: gdredu_live_3f8a9b2c) é visível na listagem para identificação. Se o segredo for perdido, uma nova key deve ser gerada e a antiga revogada.
:::

Revogação e rotação

• Revogar: Desativa a key imediatamente. Requisições posteriores retornam 401 REVOKED_API_KEY.
• Expiração: Se uma key com expiresAt definido for usada após a data, retorna 401 EXPIRED_API_KEY.
• Rotação: Crie uma nova key, atualize suas integrações, depois revogue a antiga.

Escopo: Business vs Branch

Veja Conceitos fundamentais para entender a relação Business → Branch.

Endpoint /v1/me

Para verificar sua key e ver seus scopes:

curl https://api.gdredu.com/v1/me \
  -H "Authorization: Bearer gdredu_live_sua_api_key"

Resposta:

{
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Integração ERP",
    "scopeType": "BUSINESS",
    "scopes": ["students:read", "students:write", "series:read"],
    "rateLimitPerMinute": 100
  },
  "business": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Colégio Exemplo LTDA"
  },
  "branch": null
}

Se a key for do escopo BRANCH, branch conterá o ID da unidade vinculada.

Segurança adicional

• Rate limiting: Cada key tem um limite de requisições por minuto (padrão 100). Veja Rate Limits.