Gerenciar API Keys (Guia do Administrador)

Este guia explica como administradores da GDREdu gerenciam API keys — criar, rotacionar e revogar chaves de acesso para desenvolvedores e integrações.

Pré-requisitos

Para acessar a tela de API Keys, você precisa ter uma das seguintes permissões (role) em pelo menos uma unidade:

DASH_ADMIN — Administrador do painel
DASH_MANAGER — Gestor do painel

Se você não vê a opção "API Keys" no menu lateral, entre em contato com o administrador da instituição.

Acessando a tela

Faça login no painel da GDREdu.
No menu lateral, vá em Gestão → API Keys (ou /dashboard/api-keys).

Criando uma API Key

Clique no botão "Nova API Key" no canto superior direito.
Preencha o formulário:

Campo	Descrição
Nome	Identificação interna da key (ex: "Integração ERP", "App Mobile"). Apenas para organização — não aparece para o desenvolvedor.
Escopo	Define a abrangência da key. Veja detalhes abaixo.
Unidade	(Apenas se Escopo = Unidade específica) Selecione qual campus/escola a key pode acessar.
Permissões (Scopes)	Selecione quais operações a key poderá realizar. Veja Scopes para a lista completa.
Rate limit (req/min)	Limite de requisições por minuto. Padrão: 100. Máximo: 1000.
Expira em	(Opcional) Data em que a key deixa de funcionar automaticamente.

Clique em "Criar API Key".
Importante: O segredo completo (gdredu_live_...) será exibido apenas uma vez em uma janela de confirmação.
Copie o segredo imediatamente e armazene-o em local seguro (cofre de senhas, variável de ambiente, etc.).
Clique em "Já copiei, fechar".

:::danger
O segredo completo da API key não pode ser recuperado após fechar a janela. Apenas um prefixo (ex: gdredu_live_3f8a9b2c) permanece visível na listagem para identificação. Se o segredo for perdido, rotacione a key para gerar um novo.
:::

Escopo: Instituição vs Unidade

Escopo	Descrição	Header x-branch-id
Instituição (BUSINESS)	A key pode acessar todas as unidades da instituição. Ideal para integrações corporativas multi-unidade.	Obrigatório em endpoints por unidade
Unidade específica (BRANCH)	A key só pode acessar uma unidade selecionada. Ideal para integrações de uma única escola.	Opcional (a key já sabe qual unidade é)

Listando API Keys

A tela principal mostra todas as API keys da instituição em uma tabela paginada com:

Nome — nome dado na criação
Prefixo — identificador parcial (ex: gdredu_live_3f8a9b2c)
Escopo — Instituição ou Unidade (com nome da unidade)
Permissões — badges com os scopes concedidos (passe o mouse para ver todos)
Último uso — data/hora da última requisição feita com a key
Status — Ativa ou Revogada

Use a barra de busca para filtrar por nome ou prefixo.

Rotacionando uma API Key

Rotação gera um novo segredo para uma key existente, mantendo o mesmo ID, nome, escopo e permissões. O segredo anterior deixa de funcionar imediatamente.

Na tabela, encontre a key que deseja rotacionar.
Clique no ícone de rotação (setas circulares).
Confirme a operação na janela de confirmação.
Copie o novo segredo exibido — ele também é mostrado apenas uma vez.
Atualize suas integrações com o novo segredo.

:::warning
Rotação invalida o segredo anterior.
Ao rotacionar, todas as integrações que usavam o segredo anterior passarão a receber erro 401 INVALID_API_KEY. Certifique-se de coordenar a rotação com a atualização das integrações.
:::

Revogando uma API Key

Revogação desativa a key permanentemente. Não pode ser desfeito.

Na tabela, encontre a key ativa que deseja revogar.
Clique no ícone de lixeira.
Confirme a operação na janela de confirmação.
A key muda para o status Revogada e não aceita mais requisições.

:::info
Revogação vs Exclusão:
A revogação desativa a key permanentemente, mas o registro de uso (histórico de auditoria LGPD) é preservado para fins de conformidade. Uma key revogada não pode ser reativada — é necessário criar uma nova.
:::

Boas práticas administrativas

Uma key por integração: Não compartilhe uma mesma key entre múltiplas integrações. Se uma for comprometida, você pode revogar apenas aquela sem afetar as outras.
Princípio do menor privilégio: Conceda apenas os scopes necessários. Uma integração que apenas lista estudantes não precisa de students:write.
Defina expiração: Para integrações temporárias ou de teste, defina uma data de expiração. A key deixará de funcionar automaticamente.
Revogue keys não utilizadas: Se uma key mostra "Último uso: —" há muito tempo, considere revogá-la.
Monitore o uso: O contador de requisições na tabela mostra o volume de uso. Picos inesperados podem indicar uso indevido.
Rotacione periodicamente: Para integrações críticas, rotacione a key a cada 6-12 meses como boa prática de segurança.

Próximos passos

Conceitos fundamentais — Entenda a estrutura Business → Branch
Scopes — Lista completa de permissões
Autenticação — Como o desenvolvedor usa a key nas requisições