---
title: Virtual Keys
summary: These endpoints allow you to create and manage virtual keys, which are used to authenticate requests made through the <a href="https://www.fastly.com/documentation/reference/api/ai-runtime-control">AI Runtime Control</a> gateway. Each virtual key can be configured with request-per-minute and token-per-minute rate limits, a spend-limit flag, and a failover policy.
url: https://www.fastly.com/documentation/reference/api/ai-runtime-control/virtual-keys
---

These endpoints allow you to create and manage virtual keys, which are used to authenticate requests made through the <a href="https://www.fastly.com/documentation/reference/api/ai-runtime-control">AI Runtime Control</a> gateway. Each virtual key can be configured with request-per-minute and token-per-minute rate limits, a spend-limit flag, and a failover policy.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `access_token` | string | The access token for this virtual key. This is only returned when the key is created or rotated, and cannot be retrieved again afterward. (Read-only) |
| `created_at` | string | The date and time the key was created, in RFC 3339 format. (Read-only) |
| `customer_id` | string | The ID of the customer account that owns the key. (Read-only) |
| `expires_at` | string | The date and time the key expires, in RFC 3339 format. <code>null</code> if the key doesn't expire. |
| `id` | string | The unique identifier of the virtual key. (Read-only) |
| `name` | string | The display name of the virtual key. |
| `rpm_limit` | integer | The requests-per-minute limit for this key. <code>null</code> if there is no limit. |
| `tpm_limit` | integer | The tokens-per-minute limit for this key. <code>null</code> if there is no limit. |
| `updated_at` | string | The date and time the key was last updated, in RFC 3339 format. (Read-only) |
| `user_id` | string | The ID of the user who created the key. (Read-only) |
| `provider_connection_id` | string | The ID of the provider connection to retry against. |
| `security_action` | string | The action AI Firewall takes when it detects a violation on a request made with this key. |
| `security_enabled` | boolean | Whether AI Firewall security is enabled for requests made with this key. |
| `spend_limit_enabled` | boolean | Whether a spend limit is enabled for this key. This field cannot be set when the key is created; it can only be changed with this endpoint. |
| `spend_limit_enabled_on` | string | The date and time <code>spend_limit_enabled</code> was last set to <code>true</code>, in RFC 3339 format. <code>null</code> if the spend limit has never been enabled. This timestamp is not cleared when <code>spend_limit_enabled</code> is later set back to <code>false</code>, so it can be non-null even when the spend limit is currently disabled. (Read-only) |
| `rate_limit_429_enabled` | boolean | Whether a <code>429 Too Many Requests</code> response from the provider triggers failover. |
| `server_error_5xx_enabled` | boolean | Whether a <code>5xx</code> server error response from the provider triggers failover. |
| `targets` | array | The provider connections to retry against, in order. |
| `timeout_enabled` | boolean | Whether a request timeout triggers failover. |
| `deleted_at` | string | The date and time the key was deleted, in RFC 3339 format. <code>null</code> unless the key was deleted and <code>include_deleted</code> was used to retrieve it. (Read-only) |
| `last_used_at` | string | The date and time the key was last used to make a request, in RFC 3339 format. <code>null</code> if the key has never been used. (Read-only) |
| `type` | string | The type of the resource. (Read-only) |
| `user_name` | string | The display name of the user who created the key. (Read-only) |
| `created_by` | string | The display name of the user who created the key. (Read-only) |
| `limit` | integer | The <code>limit</code> value used when making the request. |
| `next_cursor` | string | The cursor to use to request the next page of results. <code>null</code> when there are no more results. |
| `prev_cursor` | string | The cursor to use to request the previous page of results. <code>null</code> when there is no previous page. |
| `sort` | string | The <code>sort</code> value used when making the request. |
| `total` | integer | The count of results matching the request. |
| `meta` | object | Metadata about the request. |

## API endpoints

### List virtual keys

**GET** `/ai-runtime-control/v1/keys`

List the virtual keys belonging to your account.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cursor` | string | query | No | Cursor for pagination. Use the <code>next_cursor</code> value from a previous response to request the next page of results, or the <code>prev_cursor</code> value to request the previous page. |
| `include_deleted` | boolean | query | No | Include deleted virtual keys in the results. |
| `limit` | integer | query | No | Limit how many results are returned. |
| `search` | string | query | No | Filter results to virtual keys whose name contains this substring. |
| `sort` | string | query | No | Sort field. Prefix with <code>-</code> for descending order (e.g., <code>sort=-created_at</code>). |

### Create a virtual key

**POST** `/ai-runtime-control/v1/keys`

Create a new virtual key for authenticating requests through the AI Runtime Control gateway.

### Get a virtual key

**GET** `/ai-runtime-control/v1/keys/{key_id}`

Retrieve a single virtual key.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key_id` | string | path | Yes | The ID of the virtual key. |

### Delete a virtual key

**DELETE** `/ai-runtime-control/v1/keys/{key_id}`

Delete a virtual key. This also deletes any security configuration associated with the key.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key_id` | string | path | Yes | The ID of the virtual key. |

### Update a virtual key

**PATCH** `/ai-runtime-control/v1/keys/{key_id}`

Update the attributes of a virtual key. Only the fields you include are changed.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key_id` | string | path | Yes | The ID of the virtual key. |

### Rotate a virtual key

**POST** `/ai-runtime-control/v1/keys/{key_id}/rotate`

Issue a new access token for a virtual key, invalidating the previous one.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key_id` | string | path | Yes | The ID of the virtual key. |

### Get a virtual key's failover policy

**GET** `/ai-runtime-control/v1/keys/{key_id}/failover`

Retrieve the failover policy for a virtual key. A failover policy lists alternate
provider connections to retry a request against, and which error conditions trigger
a retry.
Failover is a per-account feature. If it isn't enabled on your account, this endpoint
returns a 404 response.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key_id` | string | path | Yes | The ID of the virtual key. |

### Update a virtual key's failover policy

**PUT** `/ai-runtime-control/v1/keys/{key_id}/failover`

Replace the failover policy for a virtual key.
Failover is a per-account feature. If it isn't enabled on your account, this endpoint
returns a 404 response.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key_id` | string | path | Yes | The ID of the virtual key. |