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

# API keys

> Create an API key to call your agents, scope it to one agent, give it an expiry, and revoke it.

An API key lets your own code call your agents. It does one thing: invoke. A key cannot create, change, deploy or delete anything, so a leaked key can call your agents but cannot take over your organization.

## Create a key

<Steps>
  <Step title="Open API keys">
    In the dashboard, open **API keys** and click **Create key**.
  </Step>

  <Step title="Name it and choose what it can call">
    * **Name**: what uses it, for example `Production backend`. At most 60 characters.
    * **Scope**: **All agents** in the organization, or one agent.
    * **Expires**: optional. Leave it empty and the key works until you revoke it. A date means the key stops working at the end of that day, in your time zone.

    Click **Create key**.
  </Step>

  <Step title="Copy the key">
    The key is shown once. Copy it now: Onecortex keeps only a hash of it, so nobody, including Onecortex, can show it to you again. If you lose it, create another.

    ```bash Terminal theme={null}
    export ONECORTEX_API_KEY="oc_live_..."
    ```
  </Step>
</Steps>

## Use a key

Send it as a bearer token on every call:

```http theme={null}
Authorization: Bearer $ONECORTEX_API_KEY
```

See [the invoke API](/call/invoke).

A key that is missing, unknown, revoked or expired is refused with `401` and one message for every case, `A valid Onecortex API key is required.`, so the response never tells anyone which keys exist. A key scoped to one agent, used against another, gets `404` `That agent does not exist.`

## Scope a key to one agent

A key for one agent is the safer default for anything that calls only that agent. If it leaks, only that agent can be called with it. The **Scope** column on the **API keys** page shows which agent a key is for, or **All agents**.

## Revoke a key

Open the menu at the end of the key's row and choose **Revoke**. Any application using the key stops working within 30 seconds. Revoking cannot be undone. The key stays in the list, marked **Revoked**.

To rotate a key without downtime: create the new key, deploy it to your application, then revoke the old one. **Last used** on the old key's row tells you when it stops being used. It is updated in batches, so it can lag by up to 30 seconds.

## Keep keys on the server

A key belongs in your server's environment or secret store, never in a repository, a mobile app or a web page, where anyone who reads it can call your agent.

## What you see on the page

| Column | Shows |
| - | - |
| Name | The name you gave it, and **Revoked** or **Expired** |
| Key | `oc_live_` plus the first six characters, enough to tell keys apart and not enough to use one |
| Scope | **All agents**, or the one agent's name |
| Created, Expires, Last used | When. A clock marks a key that expires within a week |