<!-- llms.txt: https://workos.com/llms.txt -->

# Environment API key

An environment API key is a standard WorkOS secret key scoped to a single environment. A platform uses it to configure the environment through the [public API](https://workos.com/docs/reference), the same way any WorkOS customer would.

The `value` is returned only in the create response. No endpoint returns it again, so store it encrypted or write it straight into the app's secrets.

:::code-group{title="Example API key"}

```json language="curl"
{
  "object": "key",
  "id": "api_key_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "Platform provisioning key",
  "expires_at": null,
  "value": "sk_example_123456789",
  "created_at": "2026-01-15T06:37:41.193Z",
  "updated_at": "2026-01-15T06:37:41.193Z"
}
```

:::

## Endpoints

- [Create an API key](https://workos.com/docs/reference/platform/api-key/create)
- [Expire an API key](https://workos.com/docs/reference/platform/api-key/expire)

## Create an API key

Creates an environment-scoped API key. The `value` in the response is the only time the full key is returned.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments/environment_01K4E21A6ZRE7VWNM4776S0JA9/api_keys" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Platform provisioning key",
        "expires_at": null
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "object": "key",
  "id": "api_key_01K4E21A6ZRE7VWNM4776S0JA9",
  "name": "Platform provisioning key",
  "expires_at": null,
  "value": "sk_example_123456789",
  "created_at": "2026-01-15T06:37:41.193Z",
  "updated_at": "2026-01-15T06:37:41.193Z"
}
```

:::

### Error responses

- **403** (`platform_not_authorized`): the platform isn't authorized on this team.
- **404** (`environment_not_found`): no such environment in this team.

## Expire an API key

Expires an API key the calling platform created, and returns `204 No Content`.

Setting a future `expires_at` rotates a key with a grace period: mint the replacement, deploy it, then expire the old key on a date the app has already moved past. Expiring an already-expired key succeeds and changes nothing, so retries are safe.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM/environments/environment_01K4E21A6ZRE7VWNM4776S0JA9/api_keys/api_key_01K4E21A6ZRE7VWNM4776S0JA9/expire" \
  --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "expires_at": "2026-06-01T00:00:00Z"
    }
BODY
```

:::

### Error responses

- **409** (`expires_at_cannot_be_extended`): the key already has an earlier expiration. Expiration can only move closer, never further out.
- **422** (`expires_at_too_far_in_future`): `expires_at` is more than 30 days out.
- **404** (`key_not_found`): no such key in this environment, or the calling platform didn't create it.

### key

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "key" | Yes | The object type. |
| `id` | string | Yes | Unique identifier of the API key. |
| `name` | string | Yes | The name of the API key. |
| `expires_at` | string | Yes | The timestamp when the API key expires, or `null` if it never expires. |
| `value` | string | Yes | The full API key value. Returned only when the key is created. |
| `created_at` | string | Yes | The timestamp when the API key was created. |
| `updated_at` | string | Yes | The timestamp when the API key was last updated. |

### POST /platform/teams/:team_id/environments/:environment_id/api_keys

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team the environment belongs to. |
| `environment_id` | string | Yes | The ID of the environment to create the key in. |
| `name` | string | Yes | The name of the API key. |
| `expires_at` | string | No | An ISO 8601 timestamp for when the key expires. Omit or pass `null` for a key that never expires. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `key` | object | The created API key, including its plaintext value. |

### POST /platform/teams/:team_id/environments/:environment_id/api_keys/:key_id/expire

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team the environment belongs to. |
| `environment_id` | string | Yes | The ID of the environment the key belongs to. |
| `key_id` | string | Yes | The ID of the API key to expire. |
| `expires_at` | string | No | An ISO 8601 timestamp for when the key should expire, no more than 30 days in the future. Omit it, or pass a time in the past, to expire the key immediately. |