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

# Manage API keys

> Create and revoke the API keys that authenticate requests to VESSL Cloud inference endpoints.

![API Keys page with a New API Key button and a table of keys showing name, masked key, status, created date, expiration, and last editor; a revoked key appears grayed out at the bottom](https://mintcdn.com/dora/SronkP2zLUPqOXHN/images/inference-api-keys-list.png?fit=max\&auto=format\&n=SronkP2zLUPqOXHN\&q=85\&s=66c8317f201752d2df038fbc6365d82a)

Example: the API Keys page with active and revoked keys

Every request to a VESSL Cloud inference endpoint carries an API key as a bearer token. You create and manage these keys yourself in VESSL Cloud, under **Settings** → **API Keys**, so you can issue a key the moment you need one and retire it the moment you don't.

Keys belong to your organization. The **API Keys** page lists every key in the organization, and each key records who last created, renamed, or revoked it.

## Create an API key

1. Open **Settings**, then select **API Keys** under **Organization**.
2. Click **New API Key**.
3. Enter an **API Key name** (up to 128 characters). Pick a name that says where the key is used, such as `prod-chat-service` or `eval-pipeline`, so you can tell keys apart later.
4. Choose when the key expires. **Set Expiration Date** is on by default with a **30 days** term; you can also pick **7**, **60**, or **90 days**. The key expires at midnight, in your local time, at the end of the last day of the term, and the exact time is shown below the selector. Turn the toggle off for a key that never expires — it then stays valid until you revoke it.
5. Click **Create**. The **Save your API Key** dialog opens with the full key.
6. Click the copy button to copy the key. To see the key first, click the eye icon.
7. Store the key somewhere safe, such as your secret manager.
8. Click **Done**.

> [!WARNING]
>
> The full key is shown only once, in the **Save your API Key** dialog. VESSL Cloud doesn't store the key in a form it can show again, so after you close the dialog you can see only its leading characters. If you lose a key, create a new one and revoke the old one.

> [!TIP]
>
> **Get started** on a model page opens a quickstart guide whose first step links straight to the **API Keys** page, so you can create a key and send your first request in one sitting.

## Use an API key

Send the key as a bearer token in the `Authorization` header of every request to `https://inference.cloud.vessl.ai/v1`. Set it as the `VESSL_API_KEY` environment variable first:

```bash theme={null}
export VESSL_API_KEY="<api-key>"
```

```bash cURL theme={null}
curl https://inference.cloud.vessl.ai/v1/chat/completions \
  -H "Authorization: Bearer $VESSL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {"role": "user", "content": "Hello! Who are you?"}
    ]
  }'
```

```python Python theme={null}
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://inference.cloud.vessl.ai/v1/chat/completions",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['VESSL_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "model": "<model-id>",
        "messages": [
            {"role": "user", "content": "Hello! Who are you?"},
        ],
    }).encode(),
)

with urllib.request.urlopen(request, timeout=120) as response:
    body = json.load(response)

print(body["choices"][0]["message"]["content"])
```

```typescript TypeScript theme={null}
const response = await fetch("https://inference.cloud.vessl.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VESSL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "<model-id>",
    messages: [
      { role: "user", content: "Hello! Who are you?" },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status} ${await response.text()}`);
}

const body = await response.json();
console.log(body.choices[0].message.content);
```

For the endpoint details and where to find the model ID, see [Send your first request](https://docs.cloud.vessl.ai/inference/send-requests.md).

Treat an API key like a password: keep it in an environment variable or a secret manager, don't commit it to source control, and don't embed it in client-side code.

## The API Keys list

Active keys appear first. Within each status, the newest keys come first.

> [!NOTE]
>
> The list shows the following columns:
>
> * **Name**: The name you gave the key
> * **Key**: The leading characters of the key, followed by a mask. The full key is never shown here.
> * **Status**: **Active**, **Expired**, or **Revoked**. See [API key status](#api-key-status).
> * **Created**: The date the key was created
> * **Expires**: The expiration date and time, or **Never** for a key without an expiration date. Revoked keys show `-`.
> * **Last edited by**: The member who last created, renamed, or revoked the key

Expired and revoked keys stay in the list, grayed out, for 30 days. After that, they no longer appear in the list.

## Permissions

| Operation | Who can perform it |
| - | - |
| View and create keys | Anyone in the organization |
| Rename and revoke keys | **Organization admin** only |

Members don't see the **⋮** menu in the list. If you're a member and think a key has leaked, ask an Organization admin to revoke it. For the admin procedures, see [Rename and revoke API keys](https://docs.cloud.vessl.ai/admin/api-keys/overview.md).

## Rename an API key

1. Click the **⋮** menu at the end of the key's row and choose **Edit**.
2. Change the **API Key name**.
3. Click **Edit**.

Only the name can be changed. The expiration date is fixed when the key is created — to get a different expiration date, create a new key and revoke the old one. See [Replace an API key without downtime](#replace-an-api-key-without-downtime).

## Revoke an API key

Revoke a key when it's no longer needed or when you suspect it has leaked.

1. Click the **⋮** menu at the end of the key's row and choose **Revoke**.
2. Type the key's name to confirm.
3. Click **Revoke**.

Revocation can't be undone. Requests that use the key start being rejected within a minute. The key stays in the list as **Revoked** for 30 days, and after that it no longer appears in the list.

For Organization admins, the **⋮** menu is shown on every row, but it's disabled for expired and revoked keys — they can't be edited or revoked again.

## Replace an API key without downtime

To switch to a new key without interrupting traffic, create the new key first and revoke the old one after your applications have moved over:

1. Create a new key. See [Create an API key](#create-an-api-key).
2. Update every application that uses the old key to send the new one.
3. Once no traffic uses the old key, revoke it. See [Revoke an API key](#revoke-an-api-key).

Keys with an expiration date make regular replacement easy: create the replacement a few days before the old key expires, switch your applications over, and let the old key expire on its own.

## API key status

| Status | Meaning | Can send requests? |
| - | - | - |
| **Active** | The key is valid. | Yes |
| **Expired** | The key passed its expiration date. | No |
| **Revoked** | The key was revoked. | No |

A request with an expired or revoked key fails with an authentication error. Create a new key and update your application to use it.


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