Autenticação da API pública: chaves, escopos e segurança

A API pública da Studeia expõe as rotas /api/institution/* para integrações. Toda requisição é autenticada por sessão (no app) ou por chave de API (Bearer). Este guia cobre as chaves, os escopos e as boas práticas.

Resposta rápida

Autentique com Bearer token (chave com prefixo mia_)
Chaves são criadas em Configurações → API Keys
Escopos no padrão recurso:ação limitam cada chave
A chave completa aparece só uma vez (servidor guarda só o hash)
Operações sensíveis aceitam apenas sessão, nunca API key

Como autenticar

Envie a chave no header Authorization:

GET /api/institution/courses
Authorization: Bearer mia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A dupla autenticação (resolveAuth) aceita sessão (no app) ou chave de API (integrações). Para chaves, a resposta inclui headers de rate limit.

Escopos (princípio do menor privilégio)

Escopos seguem o padrão recurso:ação. Exemplos:

Recurso	Leitura	Escrita
Cursos	`courses:read`	`courses:write`
Usuários	`users:read`	`users:write`
Matrículas	`enrollments:read`	`enrollments:write`
Turmas	`classes:read`	`classes:write`
Relatórios	`reports:read`	—

Crie chaves com o mínimo de escopos necessários. Uma chave usada só para leitura de relatórios não precisa de escopos de escrita.

Segurança da chave

A chave completa é exibida uma única vez na criação.
O servidor armazena apenas o hash SHA-256 — a chave não é recuperável.
Revogar/editar uma chave invalida o acesso imediatamente.
Em caso de vazamento, revogue e gere outra.

Rotas que NÃO aceitam API key

Por segurança, operações críticas exigem autenticação de sessão (sessionOnly) e nunca aceitam API key:

Gerenciamento de chaves de API.
Billing / checkout (evita automação de compras).
Moderação do supervisor IA.

Boas práticas

Use menor privilégio nos escopos.
Rotacione chaves periodicamente.
Nunca exponha a chave no frontend ou em repositórios.
Monitore o uso (cada requisição é registrada).
Trate rate limits (veja a página dedicada).

Perguntas frequentes

Como autentico? Bearer token com a chave mia_ no header Authorization.

O que são escopos? Limites recurso:ação do que a chave pode fazer.

A chave fica visível depois? Não — só na criação; servidor guarda só o hash.

Serve para qualquer rota? Para a maioria; billing, chaves e moderação são só sessão.

Veja a visão geral da API e webhooks e rate limits.

FAQ

Como autentico uma requisição na API da Studeia?

Envie a chave de API no header Authorization como Bearer token. As chaves têm o prefixo mia_ e são geradas em Configurações → API Keys da instituição. Cada requisição também passa por rate limiting, e o uso é registrado para auditoria.

O que são escopos (scopes) e por que importam?

Escopos limitam o que cada chave pode fazer, no padrão recurso:ação (ex: courses:read, users:write). Uma chave só executa operações cobertas pelos seus escopos. Crie chaves com o mínimo de escopos necessários (princípio do menor privilégio) — uma chave de leitura não deve ter escopos de escrita.

A chave de API completa fica visível depois de criada?

Não. A chave completa é exibida apenas uma vez, no momento da criação. O servidor armazena somente um hash (SHA-256), de forma que a chave não pode ser recuperada depois. Guarde-a com segurança; se perder, revogue e gere outra.

Posso usar a API key para qualquer rota institucional?

Para a maioria das rotas /api/institution/*, sim — com o escopo correto. Exceções: operações sensíveis (gerenciamento de chaves de API, billing/checkout, moderação do supervisor IA) aceitam apenas autenticação de sessão (sessionOnly), nunca API key, para evitar automação de ações críticas.