Token de API

Um token de API permite que um software terceiro chame os pontos de acesso de API do Omniscol em nome da escola, em leitura e, se pontos de acesso de API de escrita forem selecionados, em escrita.

É poderoso — portanto, deve ser manuseado com cuidado.

Geração

Um token é gerado em Compartilhamento (Importação / Exportação > Compartilhamento). Você fornece:

• uma chave (gerada no Omniscol, com rótulo e expiração eventual; a sua data de expiração pode ser alterada depois),
• um escopo: a lista de pontos de acesso de API que esse token poderá chamar (conceda apenas o que for estritamente necessário),
• eventualmente uma expiração do token. Essa data é inscrita no JWT gerado e não pode ser alterada em seguida.

Excluir a chave, ou atingir a sua expiração, revoga imediatamente os tokens derivados. Para alterar a expiração de um token individual, gere um novo JWT.

Utilização

O token é transmitido no cabeçalho HTTP Authorization: Bearer <token>, ou (menos recomendado para produção) na URL via ?auth=<token>.

Boas práticas

• Uma chave por integração — facilita a revogação independente.
• Escopo mínimo — marque apenas as APIs necessárias, não tudo por padrão.
• Expiração no nível certo — use a expiração da chave para conduzir uma integração ao longo do tempo; use a expiração do token para um acesso temporário não modificável.
• Rotação periódica — regenere a chave a cada 6-12 meses.
• Fora do Git — o token não deve acabar versionado num repositório público. Use as variáveis de ambiente do seu servidor.

Diferença em relação a OIDC / SSO

Para conectar usuários reais com a sua identidade institucional, use OIDC / SSO. O token de API destina-se a integrações técnicas servidor a servidor, não à conexão diária dos usuários.