> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating requests

> How to authenticate against the Public API, and how to use the interactive playground on these pages.

## API keys — the Public API

Public API endpoints authenticate with an API key sent as a bearer token:

```http theme={null}
Authorization: Bearer ont_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8
```

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.

<Warning>
  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.
</Warning>

### Using the playground

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

<Steps>
  <Step title="Enter your key">
    Paste it into the bearer-token field. The playground sends it as `Authorization: Bearer <your key>`.
  </Step>

  <Step title="Fill in parameters">
    For example `date=2026-06-15` on the attendance endpoint.
  </Step>

  <Step title="Send">
    The request goes to `https://app.ontime.hosai.app` — your real organization.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

### 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](/developers/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.

<Warning>
  **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.
</Warning>

## 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.