Omniscol API — authentication tokens

Key and token: two distinct objects

Omniscol distinguishes two objects that must not be confused.

A key is a persistent object, kept on the Omniscol side. It combines:

• a short identifier, randomly generated, public: it is what the list displays, and it travels in each token to designate the key to verify;
• a descriptive label, editable at any time;
• an optional expiration date, editable at any time;
• a long random secret, drawn on the server side, which serves as the cryptographic signing key.

The identifier, the label and the expiration date are administrative information: the identifier is only a public reference, not a secret element. The secret, on the other hand, is the only signing material: randomly generated when the key is created, it stays on the server side, is not editable, and is never displayed or returned — neither at creation, nor in the key list. And even if it leaked, it would not be enough to forge a token: the signature combines it with an account-specific salt and a server secret which, likewise, never leave Omniscol.

A token is a self-contained JWT (JSON Web Token), signed with the secret of the key. It is what you hand to the external system. Its signed content carries the account concerned, the list of authorized endpoints, the key it derives from and its own expiration date.

In other words: a key signs, a token is signed. The same key can sign several tokens — all verifiable with the same secret, so all revoked together if the key disappears.

Omniscol does not store the token: it generates it, displays it once, then re-verifies it on every call by recomputing its signature from the secret of the key (HMAC SHA-256). No permission carried by the token can therefore be altered without that secret.

Creating a token

The Sharing screen is available in Administration → Import/Export on Premium accounts. Creation happens in two steps: you first create a key, then generate a token from that key.

1. Create a key — enter a meaningful label and, if access is temporary, an expiration date. Its label and its expiration remain editable afterwards; its signing secret does not.
2. Generate a token — select the key, check the authorized endpoints, optionally choose an expiration date specific to the token, then generate the JWT.

At generation, Omniscol displays the token only once. Copy it immediately into a secrets manager: it will not be displayed again. The token's expiration is written into its signed content: it cannot be changed afterwards. To change that date, generate a new token.

There are therefore two levels of expiration, independent of each other:

• key expiration — editable from the key list; once it is reached, all tokens derived from that key are rejected (the call fails with a 401);
• token expiration — set at generation, written into the JWT, and not editable afterwards.

Authorized endpoints

A token only grants access to the endpoints checked at its generation: never assume it covers the whole API. The authorized list is carried in the token and verified on every call; a call to an unauthorized endpoint is rejected (401).

Beyond individual endpoints, the selection list offers per-module shortcuts:

• a module's entry on its own authorizes all of its endpoints;
• the per-operation variants — read, update, creation, deletion — restrict the module to a single call type.

Checking "Timetable [read]" thus grants full read access to timetables without opening any write access, and without checking each endpoint one by one. Keep it tight: grant only the modules and the operations strictly necessary for the integration.

Using a token

Two usual ways to send the token to the API:

• HTTP header: Authorization: Bearer <token> (recommended).
• Query string: ?auth=<token> (handy for debugging, but it appears in HTTP logs — avoid in production).

curl example, to adapt with a real endpoint taken from the OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://your-school.omniscol.com/api/<module>/<endpoint>

OpenAPI documentation

The Import/Export screen displays an OpenAPI 3.1 link that opens the specification available for the account in Swagger Editor. There you will find:

• the list of exposed API endpoints,
• the schemas of the data exchanged,
• the methods and parameters,
• the expected responses.

The specification is also served directly by your account, without authentication:

• /api/guest/openapi.json — specification in JSON format;
• /api/guest/openapi.yaml (or /api/guest/openapi?yaml=true) — same content in YAML format;
• /api/guest/school_schema.json — JSON schema of the account's data.

Revoking access

Revocation happens at the level of the key, not of the individual token.

The screen lists the keys that have been used to generate tokens. Deleting a key erases its signing secret on the Omniscol side: from then on, no signature derived from that secret can be verified any more, and any call presenting a token issued from that key fails with a 401. It is the absence of the secret that invalidates the tokens, not a revocation list.

For the IT department, two consequences:

• There is no token-by-token revocation. Omniscol does not keep the issued JWTs and cannot disable one in isolation: a token already generated remains valid until its own expiration, or until its key is deleted or expired.
• Changing a key's expiration acts immediately on all of its tokens: moving that date earlier cuts off access for every token issued from the key.

Best practice: delete without delay any key you suspect has leaked, then recreate a replacement key with a meaningful label.

One key per target and per use

Since revocation is per key, dedicate a key to each integration (one external software = one key). A key's secret only signs its own tokens: deleting that key only invalidates the access of the integration concerned, without touching the others.

Conversely, a single key shared between several systems makes any revocation all-or-nothing: deleting the compromised key cuts off at once all the systems that were using it.

Which integrations it serves

The API is typically used for:

• custom signage systems (beyond the native Omniscol display panels; see Panel customization),
• external dashboards consolidating Omniscol and other sources,
• connectors or synchronizations with an ERP or a business information system,
• MCP-compatible AI agents consuming Omniscol through the MCP server; see MCP — connect an external AI agent.

For delegated access for an identified third-party service (scoped token, user consent, revocable by disabling the client), prefer Omniscol's OAuth2 server: see OAuth2 / OIDC (provider).