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

# API keys

> Generate, use and revoke developer keys — a key is full API access to one Business Unit, and its secret is shown exactly once.

The **API keys** page lives on the Business Unit navigation, between **Members** and **Settings**. A key is a pair:

* **Key ID** (`ok_…`) — the public name of the key. Visible any time, safe to write in logs and support tickets; it identifies the key but cannot be used to call the API.
* **Secret** (`osk_…`) — the credential itself. Shown **exactly once**, right after the key is created. Orriven stores only a hash: if the secret is lost, it cannot be recovered — you generate a new key and revoke the old one.

<Warning>
  A key can read and write **everything** in its Business Unit. Treat the secret like a password: keep it in your server-side secret store, never in a browser, a mobile app, or a repository.
</Warning>

## Who can manage keys

Only organization **Owners and Admins** can view, generate or revoke keys. Planners and other roles do not have access — a key's reach is broader than their own, so issuing one is an administrator's decision.

## Generating a key

<Steps>
  <Step title="Open API keys and choose Generate key">
    Name the key after the integration it is for — "CRM sync", "check-in kiosk". The name is for your own bookkeeping.
  </Step>

  <Step title="Copy the secret from the banner">
    The full secret appears once in a banner with a copy button. The banner cannot be dismissed for a few seconds — that is your window. Once you leave, only the prefix (`osk_1a2b…`) remains visible.
  </Step>

  <Step title="Call the API">
    Send the secret as a bearer token on every request:

    ```bash theme={null}
    curl -H "Authorization: Bearer osk_…" "$BASE/v1/events"
    ```
  </Step>
</Steps>

## The key list

Each row shows the key's name, Key ID, secret prefix, pinned [API version](/en/developers/versioning), who created it, when it was last used, and its status: **Active**, **Revoked** or **Expired**. "Last used" updates as your integration calls the API — a key that shows *Never* after deployment is a sign the integration is not reaching Orriven.

## Revoking

Revoking a key kills it **immediately**: every request using it starts failing with the same `401` an unknown key gets. Revocation cannot be undone, and revoked keys stay in the list as a record. To rotate a credential, generate the new key first, switch your integration over, then revoke the old one — no downtime.

## Rules to know

* **The secret appears once.** Not in the list, not in any API response, not to support. Lost secret = new key.
* **One key, one Business Unit.** A key never sees another unit's data; a request for another unit's event answers as if the event did not exist.
* **All key activity is audited.** Generation and revocation appear in the [audit log](/en/organization/audit-logs), and every write the key performs is recorded with the key as the actor.
* **Invalid means invalid.** A missing, mistyped, revoked or expired secret all produce the identical `401` — the response never reveals whether a credential once existed.

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/en/developers/quickstart">
    First calls with your new key.
  </Card>

  <Card title="Members & roles" icon="users" href="/en/organization/members-roles">
    Why key management is Owner/Admin only.
  </Card>
</CardGroup>