# API keys

> Create, scope and manage keys for the API.

Source: https://reverie.im/en/docs/integrations/api-keys
Language: en

An API key authenticates requests to Reverie's [Open API](https://reverie.im/en/docs/integrations/open-api). Keys live at **Settings → More → API Keys**, which is also where the Labs **Open API** tile points. Any account can create them — there is no tier requirement and no cap on how many you hold.

## Create a key \[#create-a-key]

### Press Create New API Key \[#press-create-new-api-key]

On an empty page the button reads **Create Your First API Key**.

### Name it \[#name-it]

**Name** is required, 1–100 characters. It is how the key is labelled in the list and in usage statistics — "Living Room Speaker", "staging worker".

### Choose Global or a specific character \[#choose-global-or-a-specific-character]

**Character Selection** is a choice between **Global (All Characters)** and **Specific Character**, not an optional extra. A specific character becomes the key's pinned character.

### Optionally set a device type and an expiry \[#optionally-set-a-device-type-and-an-expiry]

**Device Type** is free text (`speaker`, `phone`, `iot`). **Expiration** takes a date *and* a time; the key stops working automatically at that moment.

The key appears immediately as `rk_` followed by 64 hexadecimal characters.

## Keys stay retrievable \[#keys-stay-retrievable]

The secret is not a one-time reveal. Every key's card has **Show API key**, **Hide API key** and **Copy API key**, at any time, for as long as the key exists.

> Because the full secret remains readable from your settings, treat account
> access as key access. Keep the key on a server or in a secret manager, never
> in source control or browser code.

## Global keys and pinned keys \[#global-keys-and-pinned-keys]

|                       | **Global (All Characters)**         | **Specific Character**                                             |
| --------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `GET /models` returns | Your recent characters              | That character's scenarios, or the character itself if it has none |
| `model` omitted       | Falls back to your most recent chat | Uses the pinned character                                          |
| Short scenario IDs    | Never resolve                       | Resolve against the pinned character                               |

## Disable, delete, rotate \[#disable-delete-rotate]

| Action            | Effect                                                     | Reversible |
| ----------------- | ---------------------------------------------------------- | ---------- |
| **Active** toggle | Requests with the key are rejected while it is off         | Yes        |
| **Delete**        | The key is destroyed and applications using it lose access | No         |

There is no separate revoke action — disabling and deleting are the two options.

> Deleting a key cannot be undone, and it takes that key's attribution with
> it: its past traffic moves into a **Deleted keys** bucket in the usage
> statistics, where you can no longer tell which integration spent what.
> Disable a key first if you might want the history.

To rotate, create the replacement, deploy it, then disable or delete the old key. There is no automatic rotation and no grace period after expiry — an expired key is rejected with `api_key_expired` on the next request.

## Scopes \[#scopes]

Keys carry scopes, and the create dialog does not expose them. A key you make in Settings can call the chat endpoints, and only those.

The character importer endpoint needs a different scope, and the only way to get such a key is to open **Labs → Character Importer Skill**, which creates one for you named **Reverie Character Importer (Skill)**. Calling the importer with an ordinary settings key returns a 403. [Import characters →](https://reverie.im/en/docs/characters/import-characters)

## Usage statistics \[#usage-statistics]

The **Usage statistics** panel on the same page reports **Requests**, **Tokens**, **Credits** and **Active keys**, bucketed by UTC day, with a per-key breakdown under **Usage by key**. Filter by one key or **All keys**, over a window of 7 to 90 days — 30 by default. Only chats created through the API are counted.

This panel is the only place per-key spend exists. Your credit history records what each message cost, but it does not label a transaction with the key that made it, so use the statistics here to compare integrations.

## Build a request \[#build-a-request]

**Build a request** opens a generator: pick one of your active keys, pick a character or scenario from the list that key can see, type a message, choose streaming and temperature, then copy working cURL, TypeScript or Python.

The key is used in your browser only to load the character list. The generated code reads `REVERIE_API_KEY` from the environment rather than embedding the secret.

## Limits \[#limits]

| Limit                      | Value                                           |
| -------------------------- | ----------------------------------------------- |
| Keys per account           | No limit                                        |
| Per-key rate limit         | None                                            |
| Per-key concurrency cap    | None                                            |
| What actually bounds usage | Your credit balance, plus the free-model window |

## Related \[#related]

* [Open API](https://reverie.im/en/docs/integrations/open-api) — endpoints, request shape and errors
* [Import characters](https://reverie.im/en/docs/characters/import-characters) — what the importer key is for
* [Reverie Labs](https://reverie.im/en/docs/integrations/labs) — the Open API and importer tiles
* [Security](https://reverie.im/en/docs/account/security) — the rest of your account's access settings