API Omniscol — tokens de autenticação

Chave e token: dois objetos distintos

O Omniscol distingue dois objetos que não se deve confundir.

Uma chave é um objeto persistente, conservado do lado do Omniscol. Ela reúne:

• um identificador curto, gerado aleatoriamente, público: é ele que a lista exibe, e ele viaja em cada token para designar a chave a verificar;
• um rótulo descritivo, modificável a qualquer momento;
• uma data de expiração facultativa, modificável a qualquer momento;
• um segredo aleatório longo, sorteado do lado do servidor, que serve de chave de assinatura criptográfica.

O identificador, o rótulo e a data de expiração são informações de administração: o identificador é apenas uma referência pública, não um elemento secreto. O segredo, por sua vez, é o único material de assinatura: gerado aleatoriamente na criação da chave, permanece do lado do servidor, não é modificável, e nunca é exibido nem devolvido — nem na criação, nem na lista das chaves. E mesmo se ele vazasse, não bastaria para forjar um token: a assinatura o combina com um sal próprio à conta e a um segredo do servidor que, também eles, nunca saem do Omniscol.

Um token é um JWT (JSON Web Token) autônomo, assinado com o segredo da chave. É ele que você transmite ao sistema externo. O seu conteúdo assinado carrega a conta em questão, a lista dos pontos de acesso autorizados, a chave da qual ele deriva e a sua própria data de expiração.

Em outras palavras: uma chave assina, um token é assinado. Uma mesma chave pode assinar vários tokens — todos verificáveis com o mesmo segredo, portanto todos revogados juntos se a chave desaparecer.

O Omniscol não armazena o token: ele o gera, o exibe uma vez, depois o reverifica a cada chamada reconstituindo a sua assinatura a partir do segredo da chave (HMAC SHA-256). Nenhuma autorização carregada pelo token pode, portanto, ser alterada sem esse segredo.

Criar um token

A tela Compartilhamento está disponível em Administração → Importação / Exportação nas contas Premium. A criação faz-se em dois tempos: cria-se primeiro uma chave, depois gera-se um token a partir dessa chave.

1. Criar uma chave — informe um rótulo esclarecedor e, se o acesso for temporário, uma data de expiração. O seu rótulo e a sua expiração permanecem modificáveis depois; o seu segredo de assinatura, não.
2. Gerar um token — selecione a chave, marque os pontos de acesso autorizados, escolha eventualmente uma data de expiração própria ao token, depois gere o JWT.

Na geração, o Omniscol exibe o token uma única vez. Copie-o imediatamente para um gerenciador de segredos: ele não será mais reexibido. A expiração do token está inscrita no seu conteúdo assinado: ela não se modifica a posteriori. Para alterar essa data, gere um novo token.

Há, portanto, dois níveis de expiração, independentes um do outro:

• expiração da chave — modificável a partir da lista das chaves; quando ela é atingida, todos os tokens derivados dessa chave são recusados (a chamada falha com um 401);
• expiração do token — fixada na geração, inscrita no JWT, e não modificável em seguida.

Pontos de acesso autorizados

Um token dá acesso apenas aos pontos de acesso marcados na sua geração: nunca presuma que ele cobre toda a API. A lista autorizada é transportada no token e verificada a cada chamada; uma chamada a um ponto de acesso não autorizado é recusada (401).

Além dos pontos de acesso individuais, a lista de seleção propõe atalhos por módulo:

• a entrada de um módulo sozinha autoriza todos os seus pontos de acesso;
• as variantes por operação — leitura, modificação, criação, exclusão — restringem o módulo a um único tipo de chamada.

Marcar « Horário [leitura] » concede assim toda a leitura dos horários sem abrir a mínima escrita, sem marcar cada ponto de acesso um a um. Fique no mais justo: conceda apenas os módulos e as operações estritamente necessárias à integração.

Utilizar um token

Duas maneiras usuais de enviar o token à API:

• Cabeçalho HTTP: Authorization: Bearer <token> (recomendado).
• Query string: ?auth=<token> (prático para o debug, mas aparece nos logs HTTP — a evitar em produção).

Exemplo curl, a adaptar com um ponto de acesso real extraído do OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://sua-escola.omniscol.com/api/<module>/<ponto-de-acesso>

Documentação OpenAPI

A tela Importação / Exportação exibe um link OpenAPI 3.1 que abre a especificação disponível para a conta no Swagger Editor. Você aí encontrará:

• a lista dos pontos de acesso de API expostos,
• os esquemas dos dados trocados,
• os métodos e parâmetros,
• as respostas esperadas.

A especificação também é servida diretamente pela sua conta, sem autenticação:

• /api/guest/openapi.json — especificação no formato JSON;
• /api/guest/openapi.yaml (ou /api/guest/openapi?yaml=true) — mesmo conteúdo no formato YAML;
• /api/guest/school_schema.json — esquema JSON dos dados da conta.

A ajuda completa para o seu assistente de IA

O portal também publica toda a ajuda do Omniscol em um único arquivo de texto, pronto para servir de base de conhecimento a um assistente de IA (projeto Claude, GPT personalizado…):

• omniscol.com/pt/llms-full.txt — o guia completo em Markdown, disponível em cada idioma da ajuda (/en/llms-full.txt, /fr/llms-full.txt…);
• omniscol.com/llms.txt — o índice no padrão llms.txt, descoberto automaticamente pelos motores de IA.

Revogar um acesso

A revogação faz-se ao nível da chave, não do token individual.

A tela lista as chaves que serviram para gerar tokens. Excluir uma chave apaga o seu segredo de assinatura do lado do Omniscol: a partir daí, nenhuma assinatura derivada desse segredo pode mais ser verificada, e toda chamada que apresente um token oriundo dessa chave falha com um 401. É a ausência do segredo que invalida os tokens, não uma lista de revogação.

Para o departamento de TI, duas consequências:

• Não há revogação token por token. O Omniscol não conserva os JWT emitidos e não pode desativar um isoladamente: um token já gerado permanece válido até a sua própria expiração, ou até que a sua chave seja excluída ou expirada.
• Modificar a expiração de uma chave age imediatamente sobre todos os seus tokens: adiantar essa data corta o acesso do conjunto dos tokens oriundos da chave.

Boa prática: exclua sem esperar toda chave cujo vazamento você suspeite, depois recrie uma chave de substituição com um rótulo esclarecedor.

Uma chave por alvo e por uso

Já que a revogação é por chave, dedique uma chave a cada integração (um software externo = uma chave). O segredo de uma chave só assina os seus próprios tokens: excluir essa chave só invalida os acessos da integração em questão, sem tocar nos outros.

Ao contrário, uma chave única compartilhada entre vários sistemas torna toda revogação abrupta: excluir a chave comprometida corta de uma vez todos os sistemas que a usavam.

Para quais integrações

A API é tipicamente utilizada para:

• sistemas de signage personalizados (além dos painéis de exibição Omniscol nativos; veja Personalização dos painéis),
• dashboards externos consolidando o Omniscol e outras fontes,
• conectores ou sincronizações com um ERP ou um SI de negócio,
• agentes IA compatíveis com MCP consumindo o Omniscol via o servidor MCP; veja MCP — conectar um agente IA externo.

Para um acesso delegado a um serviço terceiro identificado (token com escopo, consentimento do usuário, revogável desativando o cliente), prefira o servidor OAuth2 do Omniscol: veja OAuth2 / OIDC (provedor).