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

# API keys

> Create API keys for your organization, choose which models each key can use, and revoke keys you no longer need.

API keys let your apps, scripts, and services call DeepMask models through the [DeepMask API](https://documentation.deepmask.io/api/overview.md). Keys belong to your organization, not to a person. Each key can use only the models you grant to it, and it can have its own monthly spending cap.

You manage keys on the **Keys** tab of **User Settings** > **API**. To get there, click your name at the bottom of the chat sidebar, choose **User Settings**, and select **API** in the settings sidebar.

> [!NOTE]
>
> Only organization admins see **API** in the settings sidebar. Every admin can create, review, and revoke all of your organization's keys.

## Before you start

To create a key, your organization needs:

* An active paid plan: Pro, Power, or Enterprise. The Free plan doesn't include API access. A trial, or a plan with an overdue payment, doesn't count.
* API billing enabled. Open the **Billing** tab and click **Enable API billing**. See [Billing](https://documentation.deepmask.io/api/billing.md).
* No API invoice with a failed payment.
* No usage review in progress. While DeepMask reviews recent usage, you can't create keys. See [When requests are paused](https://documentation.deepmask.io/api/errors.md#when-requests-are-paused).

If any of these is missing, **Create key** is unavailable and a notice at the top of the page tells you what to fix.

## Creating a key

**1. Open the Keys tab**

Go to **User Settings** > **API** and stay on the **Keys** tab. Click **Create key**.

**2. Name the key**

Enter a **Key name** that identifies the app or environment, such as "Production service". Names can have 1–80 characters, without control characters such as tabs or line breaks.

**3. Set a key spending cap (optional)**

Enter an amount in euros under **Key spending cap (optional)** to limit what this key can spend each month. Leave it empty to rely on the organization-wide cap only.

**4. Choose the key's models**

Under **Model access**, keep **Choose models** and select the models this key can use. Or choose **All current models** to grant every model in the catalog today.

**5. Create the key**

Click **Create key** at the bottom of the dialog. DeepMask shows the new key once, so copy and store it right away.

![Create API key dialog with the key name Support assistant, a Key spending cap of €100, and Model access set to Choose models, with provider groups under a search field and 4 of 26 models selected.](https://mintcdn.com/deepmaskgmbh/Tc7tJrGOE8MSnXNJ/images/api/create-key.jpg?fit=max\&auto=format\&n=Tc7tJrGOE8MSnXNJ\&q=85\&s=a3eac9c26e6a2ccf993d83e6f5003ed3)

Name the key, set an optional cap, and pick the models it can use.

### Choosing models

**Model access** offers two options:

| Option | What the key gets |
| - | - |
| **Choose models** | Only the models you select. This is the default. |
| **All current models** | Every model in the catalog at the moment you create the key. The label shows how many models that is. Models added to the catalog later aren't included. |

With **Choose models**, models are grouped by provider:

* Type in **Search models** to filter by model name, ID, or provider.
* Provider groups start collapsed. Click a provider to show or hide its models. When you search, every matching group opens.
* The count next to a provider, such as `2/12`, shows how many of its models you selected.
* Click **Select all** or **Clear** to change a whole provider at once. While you search, these buttons read **Select matches** and **Clear matches**.
* Click the ⓘ button next to a model to see its details, including its context window, image input and tool calling support, and pricing. See [Model details while creating a key](https://documentation.deepmask.io/api/models.md#model-details-while-creating-a-key).

The dialog footer shows how many models you selected, for example "4 of 26 selected." Each key needs at least one model and can have up to 100.

> [!NOTE]
>
> **Image input** in a model's details refers to the API. A model can show **Not supported** even when it accepts images in DeepMask Chat. If your app sends images, grant at least one model that shows **Supported**. You can't add models to a key later. See [Image input](https://documentation.deepmask.io/api/models.md#image-input) for the models that accept images and [Image limits](https://documentation.deepmask.io/api/chat-completions.md#image-limits) for the limits.

See [Models](https://documentation.deepmask.io/api/models.md) to compare models and find their IDs before you choose.

### Setting a key spending cap

A key spending cap limits one key's monthly model costs and can't be more than the **Gateway spending cap**, which is the organization-wide cap shared by all keys. See [Key spending caps](https://documentation.deepmask.io/api/spending-caps.md#key-spending-caps) for the rules and how both caps work together.

## Saving your key

After you click **Create key**, the dialog changes to **Save your API key**. It shows the key's name, its number of models, and the full key under **API key**. Keys start with `sk-` followed by 64 hexadecimal characters.

**1. Copy the key**

Click **Copy key**. The button changes to **Key copied**. If copying fails, the key is selected so you can copy it yourself.

**2. Store it securely**

Save the key in your secret manager or as an environment variable, such as `DEEPMASK_API_KEY`.

**3. Close the dialog**

Click **I’ve saved it**. This is the only way to close the dialog while the key is shown.

> [!WARNING]
>
> DeepMask shows the full key only once. After you close the dialog, only its last four characters remain visible. If you reload the page or switch organizations before you copy the key, you can't see it again, but the key stays in your list and keeps working. If you lose a key, revoke it and create a new one.

### Testing your key

Before you click **I’ve saved it**, you can test the key from the same dialog.

**1. Set the environment variable**

Set `DEEPMASK_API_KEY` in your terminal, for example with `export DEEPMASK_API_KEY="sk-..."`.

**2. Copy the test command**

Expand **Test your key** and click **Copy command**.

**3. Run the command**

Run the command in the same terminal where you set the variable. It sends "Hello" to one of the key's models. A JSON response with a reply means the key works.

The command works in macOS and Linux shells such as bash or zsh. On Windows, use WSL or Git Bash.

The dialog gives you only a cURL command. To test from code with the Python or Node.js OpenAI SDK, see [Make your first request](https://documentation.deepmask.io/api/quickstart.md#make-your-first-request).

## Reviewing your keys

The **Keys** tab lists your organization's keys, newest first. The number on the tab counts every key that isn't revoked.

![Keys tab of the API settings page with the Base URL, three keys named Production service, Staging, and Data pipeline with model counts and key cap usage, the Create key button, and a collapsed Revoked keys section.](https://mintcdn.com/deepmaskgmbh/Tc7tJrGOE8MSnXNJ/images/api/keys.jpg?fit=max\&auto=format\&n=Tc7tJrGOE8MSnXNJ\&q=85\&s=c737024d8f94b4cee8f637fc5ee8858e)

The Keys tab lists each key with its models, status, and cap usage.

Each key shows:

| Detail | What it tells you |
| - | - |
| Name | The name you gave the key. |
| Last characters | `••••` followed by the key's last four characters, such as `••••9b3e`. Use them to match a key in your app to its row. |
| Created date | When the key was created, for example "Created Oct 14, 2026". |
| Key cap | Shown only when the key has a cap. For example, "Key cap: €4.12 of €25.00 used · resets Dec 1, 2026". |
| Models | Provider logos and the number of models the key can use, such as "3 models". |
| Status | A label that appears only when the key isn't active, such as **Inactive**. See [Key statuses](#key-statuses). |
| Actions menu | The **⋮** button with **Edit spending cap** and **Revoke**. |

The key cap line changes as the key spends, for example when the cap is reached. See [How the key list shows cap usage](https://documentation.deepmask.io/api/spending-caps.md#how-the-key-list-shows-cap-usage) for each variant.

Dates show in your local time zone, so the reset at 00:00 UTC on the 1st can appear as the last day of the previous month.

### Viewing a key's models

Click the model count on a key, such as **3 models**, to expand its **Model access** list. Each model shows its name and, when it differs, its API model ID. Click a model to copy its ID for the `model` field of your requests.

Your app can also call `GET /v1/models` with the key. It returns only the models that key can use. See [Models](https://documentation.deepmask.io/api/models.md).

## Key statuses

| Status | What it means for you |
| - | - |
| **Pending** | DeepMask is setting up the new key. This takes a moment. If setup doesn't finish, DeepMask revokes the key automatically. |
| **Active** | The key works. Active keys show no status label. |
| **Inactive** | The key itself is fine, but your organization can't make API requests right now. The key returns to **Active** on its own once the cause is fixed. See [Why a key is inactive](#why-a-key-is-inactive). |
| **Revoking** | You revoked the key, and DeepMask is finishing the revocation. Requests with the key are already refused. Click **Refresh** to check. |
| **Revoked** | The key no longer works and can't be restored. It moves to **Revoked keys**. |

## Why a key is inactive

A key shows **Inactive** when something on your organization's account blocks API requests. The notice at the top of the **API** page tells you the cause and how to fix it. See [Account notices](https://documentation.deepmask.io/api/billing.md#account-notices) for every notice and what to do about it.

Keys also show **Inactive** while API access for your organization is being set up. The notice then says "API access is being set up. New keys stay inactive until it’s ready." A key can also show **Inactive** for a moment while a change to your account is applied. If a key stays **Inactive** and no notice explains why, open the **Billing** tab and check the **API billing** status.

While a key is **Inactive**, your app's requests with it are refused. Depending on the cause, your app gets one of these errors:

* `403` `API_SUBSCRIPTION_INACTIVE`: your paid plan or API billing isn't active.
* `403` `API_SUBSCRIPTION_INACTIVE` or `402` `API_PAYMENT_FAILED`: an API invoice payment failed. Most failed payments make the subscription past due and return `403`. See [If a payment fails](https://documentation.deepmask.io/api/billing.md#if-a-payment-fails).
* `503` `API_ADMISSION_UNAVAILABLE`: API access for your organization is still being set up, a change to your account is still being applied, or requests are paused while DeepMask reviews recent usage. [Unclear outcomes](https://documentation.deepmask.io/api/limits.md#unclear-outcomes), such as provider errors or broken streams, pause requests only when your organization has more than 20 within 24 hours. Usage that DeepMask can't verify yet can also pause requests. See [When requests are paused](https://documentation.deepmask.io/api/errors.md#when-requests-are-paused).
* `503` `API_ACCOUNTING_REVIEW`: requests are paused while DeepMask reviews recent usage, and the request was already being processed when the pause began.
* `401` `API_CREDENTIAL_INVALID`: your organization's API account is closed.

See [Errors and retries](https://documentation.deepmask.io/api/errors.md) for how to handle these errors.

Your keys aren't revoked while they're inactive. You can still revoke them. You can't create new keys while a cause listed in [Before you start](#before-you-start) applies. While API access is being set up, you can still create keys, but they stay **Inactive** until it's ready.

## Editing a key's spending cap

To add, change, or remove a key's cap, click **⋮** next to the key and choose **Edit spending cap**. See [Add, change, or remove a key cap](https://documentation.deepmask.io/api/spending-caps.md#add-change-or-remove-a-key-cap) for the steps.

## Changing a key's models

You can't change which models an existing key can use. This also means **All current models** never picks up models added to the catalog later.

To give an app a different set of models, replace its key:

**1. Create a new key**

Click **Create key** and choose the models the app needs.

**2. Update your app**

Replace the old key in your app's secret store or environment, then deploy the change.

**3. Revoke the old key**

Once your app works with the new key, revoke the old one.

## Revoking a key

Revoke a key when an app no longer needs it, or right away if the key may have leaked.

**1. Open the key's actions**

Click **⋮** next to the key and choose **Revoke**.

**2. Confirm**

In **Revoke this key?**, click **Revoke**. Apps using the key lose access immediately. This can't be undone.

DeepMask confirms with "Key revoked". If you see "Revoking the key. Refresh to check." instead, the key shows **Revoking** until DeepMask finishes. Click **Refresh** to update it.

You can revoke any key at any time, including keys that show **Inactive**. The key list stays available even if models, logs, or invoices fail to load, so you can still revoke a key in an emergency.

### Revoked keys

Revoked keys move to **Revoked keys** below your key list. The section starts collapsed and shows how many revoked keys you have, such as **Revoked keys (1)**. Click it to see each key's name, last characters, revocation date, and model count. It lists up to 150 revoked keys, most recently created first.

Requests made with a revoked key keep its name in the **Request log**. See [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md).

## Security best practices

* **Use one key per app and environment.** For example, create separate keys for "Production service" and "Staging". You can then revoke one without affecting the others. The **Request log** also shows which key made each request. Your organization's **Requests per minute**, **Tokens per minute**, and **Concurrent requests** limits apply to all keys together, so extra keys don't raise them. See [Fair use](https://documentation.deepmask.io/api/limits.md#fair-use).
* **Name keys clearly.** Key names don't have to be unique, so pick names that tell your keys apart.
* **Grant only the models an app needs.** Use **Choose models** instead of **All current models** when an app needs a few models.
* **Set a key spending cap.** A cap limits what a single key can spend if it's misused.
* **Keep keys out of your code.** Store keys in a secret manager or an environment variable such as `DEEPMASK_API_KEY`. Never commit a key to source control.
* **Call the API from your server.** Never put a key in browser, mobile, or desktop app code, where anyone can extract it.
* **Rotate keys regularly.** Create a new key, update your app, confirm it works, then revoke the old key.
* **Revoke leaked keys immediately.** If a key may be exposed, revoke it first. Then create a replacement and review the **Request log** for requests you don't recognize.
* **Review your admins.** Every organization admin can manage all API keys. Keep your list of admins current. See [Team management](https://documentation.deepmask.io/enterprise/team-management.md).

## Troubleshooting

> [accordion] Create key is unavailable
>
> Your organization needs an active paid plan, active API billing, no API invoice with a failed payment, and no usage review in progress. Check the notice at the top of the **API** page. The **Create key** button stays disabled until all of these are in place. If the dialog shows "Active Chat and API subscriptions are required to create a key", close it, click **Refresh**, and fix the cause shown in the notice. See [Billing](https://documentation.deepmask.io/api/billing.md).
>
> **Create key** is also unavailable when the model list couldn't load. If an error appears at the top of the page, click **Try again**.

> [accordion] “Revoke an existing key before creating another”
>
> Your organization can have up to 50 keys that aren't revoked. Keys that show **Pending** or **Revoking** count too. Revoke a key you no longer need, then try again. See [Account limits](https://documentation.deepmask.io/api/limits.md#account-limits).

> [accordion] “Key creation could not be completed”
>
> DeepMask couldn't finish setting up the key, so it never showed you a secret. The failed key is revoked automatically. Click **Refresh**, then create the key again.

> [accordion] “Too many API management changes. Retry shortly.”
>
> Your organization can make up to 20 changes per minute on the **API** page, shared by all admins. Creating and revoking keys, saving caps, enabling, canceling, or keeping API billing, and clicking **Refresh** all count. Viewing the page doesn't. Wait a minute and try again. See [Account limits](https://documentation.deepmask.io/api/limits.md#account-limits).

> [accordion] Your app gets API\_CREDENTIAL\_INVALID
>
> The key is missing, mistyped, or revoked. Check that the request sends exactly one `Authorization: Bearer <key>` header. Then check that the key's last characters match a key in your list that doesn't show **Pending** or **Revoking** and isn't under **Revoked keys**. See [Errors and retries](https://documentation.deepmask.io/api/errors.md).

> [accordion] Your app gets API\_MODEL\_NOT\_ALLOWED
>
> The key can't use the model in the request. Expand the key's models on the **Keys** tab and copy a granted model ID. To use another model, create a new key that includes it.

> [accordion] Your app gets API\_KEY\_SPENDING\_CAP
>
> The key reached its own spending cap. Raise or remove the cap with **Edit spending cap**, or wait for the reset at 00:00 UTC on the 1st. Your other keys keep working. See [Spending caps](https://documentation.deepmask.io/api/spending-caps.md).

## Related pages

> [card] [Spending caps](https://documentation.deepmask.io/api/spending-caps.md)
>
> Set the organization-wide cap and caps for each key.

> [card] [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md)
>
> See which keys make requests and what they cost.

> [card] [Limits and fair use](https://documentation.deepmask.io/api/limits.md)
>
> See the rate, token, and account limits that apply to your keys.

> [card] [Errors and retries](https://documentation.deepmask.io/api/errors.md)
>
> Handle authentication and access errors in your app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.