Skip to main content

​
The header

Send your key as a bearer token:
An X-Api-Key header is also accepted with the same value:
Prefer Authorization: Bearer — it is what the API Reference playground uses and what most HTTP clients handle natively.

​
Key format

The first twelve characters (ont_ plus eight hex) are the public prefix. OnTime indexes on it to find the key row, then verifies the full value against a stored hash.
The prefix is not secret and is safe to log — it identifies which key was used without revealing it. The remaining 32 characters are the secret.

​
Issuing a key

In the admin console: API & webhooks → Issue key. Requires the api:manage permission.
The plaintext key is returned exactly once, at the moment of issue. OnTime stores only a bcrypt hash of it. Lose it and your only option is to revoke and reissue.

​
Revoking

Immediate — a revoked key is refused on its next request with 401.
There is no rotate action. To rotate without downtime: issue a new key, deploy it to your consumer, confirm it works, then revoke the old one.

​
Scopes

A key is issued with a scope of ReadOnly or ReadWrite.
Both scopes currently grant identical access. Every key resolves to employee:read and attendance:read — the exact permissions the two public endpoints need.A ReadWrite key does not grant write access, because there is no public write route to grant it against. The scope column records your operational intent and is the seam a future write endpoint would gate on. Do not build on the assumption that ReadWrite means anything today.
This is deliberate. Granting employee:write to a credential with nothing to write it against would mean that the day a write route is mounted under a path a key can reach, every ReadWrite key ever issued silently acquires it — retroactively, with no reissue and no audit trail.

​
What a key acts as

A key belongs to an organization, not to a person.
  • Every request under a key is scoped to that organization. There is no way to reach another organization’s data with it.
  • The key’s permissions come from its scope, not from any employee’s role.
  • Requests are attributed in logs to the key, not to a user.
This differs from the MCP server, where a key is bound to a specific employee and acts with exactly that employee’s permissions and scope. If you need an integration that acts as a person — respecting their approval scope — that is MCP’s model, not the REST API’s. See the AI & MCP tab.
The non-public routes under /api/* authenticate differently: a signed, httpOnly session cookie set at login, checked on every request against a live session record. This is what the OnTime web and mobile apps use. It is stateful — revoking a session takes effect immediately rather than waiting for a token to expire.
Do not build an integration on session cookies. It would mean storing a user’s password, the session can be revoked out from under you by any administrator, and the routes behind it are internal and may change without notice. Use an API key.

​
Handling keys safely

1

Never commit one

Environment variables or a secrets manager. The ont_ prefix makes keys easy to detect in secret-scanning tools — use one.
2

One key per consumer

So you can revoke a single integration without breaking every other one, and so the last-used timestamp tells you something.
3

Log the prefix, never the key

The first twelve characters identify which key was used and are safe to record.
4

Revoke on personnel change

A key does not belong to a person, so nothing revokes it automatically when someone leaves.