API token

An API token allows third-party software to call Omniscol's API endpoints on behalf of the school, for reading and, if write API endpoints are selected, for writing.

It is powerful — so handle it with care.

Generation

A token is generated in Sharing (Import/Export > Sharing). You provide:

• a key (generated in Omniscol, with a label and an optional expiration; its expiration date can be changed later),
• a scope: the list of API endpoints this token will be able to call (grant only what is strictly necessary),
• optionally a token expiration. This date is written into the generated JWT and cannot be changed afterwards.

Deleting the key, or reaching its expiration, immediately revokes the derived tokens. To change the expiration of an individual token, generate a new JWT.

Usage

The token is sent in the HTTP header Authorization: Bearer <token>, or (less recommended for production) in the URL via ?auth=<token>.

Best practices

• One key per integration — makes independent revocation easier.
• Minimal scope — only check the APIs you need, not everything by default.
• Expiration at the right level — use the key expiration to manage a long-lived integration; use the token expiration for temporary, non-modifiable access.
• Periodic rotation — regenerate the key every 6-12 months.
• Not in Git — the token must not end up versioned in a public repository. Use your server's environment variables.

Difference from OIDC / SSO

To sign in real users with their institutional identity, use OIDC / SSO. The API token is meant for server-to-server technical integrations, not for users' daily sign-in.