Skip to main content

​
API keys — the Public API

Public API endpoints authenticate with an API key sent as a bearer token:
An X-Api-Key header with the same value is also accepted.

​
Getting a key

In the admin console: API & webhooks → Issue key. You need the api:manage permission, which the Admin preset carries.
The key is shown exactly once. OnTime stores only a hash of it — there is no way to retrieve it afterwards. Lose it and you must revoke and reissue.

​
Using the playground

Each endpoint page on this reference has a Try it panel.
1

Enter your key

Paste it into the bearer-token field. The playground sends it as Authorization: Bearer <your key>.
2

Fill in parameters

For example date=2026-06-15 on the attendance endpoint.
3

Send

The request goes to https://app.ontime.hosai.app — your real organization.
The playground calls production. There is no sandbox environment. Every request reads your organization’s live data and counts against your rate limit.The two Public API endpoints are read-only, so exploring them is safe. Be more careful with the platform routes, which include writes.

​
Scopes

A key is issued as ReadOnly or ReadWrite. Both currently grant identical access — employee:read and attendance:read — because the public surface has no write endpoints. See Authentication for why.

​
Rate limit

600 requests per minute per key.

​
Session cookies — the platform routes

The rest of /api/* authenticates with a signed, httpOnly session cookie set at POST /api/auth/login and validated against a live session record on every request. This is what the OnTime web and mobile apps use. Two consequences:
  • Revocation is immediate. Ending a session takes effect at once rather than waiting for a token to expire.
  • The playground cannot authenticate these routes. A browser will not attach an OnTime session cookie to a request from this documentation site, so platform endpoints in the playground will return 401. They are documented for reading, not for calling from here.
Do not build an integration on session cookies. It requires storing a user’s password, the session can be revoked by any administrator, and the routes behind it are unversioned. Use an API key against the Public API.

​
The MCP server

POST /api/mcp authenticates differently again — an employee-bound API key or an OAuth access token, resolved into a specific employee’s identity so that permissions and scope apply exactly as they do in the app. It speaks JSON-RPC and is not part of this reference. See the AI & MCP tab.

​
Biometric ingest

/api/ingest/biometric/* authenticates with a shared connector secret and is called only by the OnTime connector running on your network. It is deliberately outside both session and API-key auth. See the Biometric Terminals tab.