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

# API Keys

> Create and manage project API keys

API keys provide programmatic access to the ezForge control plane. Keys are scoped to a project and can have granular permissions.

**Required scope:** `servers:write` (to create/delete keys)

***

## List API keys

```
GET /v1/projects/:projectId/keys
```

Returns metadata for all API keys in the project. **The actual key value is never returned after creation.**

**Query parameters:** Standard [pagination](/api-reference/overview#pagination) (`limit`, `cursor`)

**Response `200`:**

```json theme={null}
{
  "data": [
    {
      "id": "key_abc123",
      "name": "ci-deploy",
      "prefix": "ezf_live_",
      "scopes": ["deployments:write", "servers:read"],
      "projectId": "proj_abc123",
      "createdAt": "2026-01-15T10:00:00Z",
      "expiresAt": "2027-01-15T10:00:00Z",
      "lastUsedAt": "2026-03-09T18:32:00Z"
    }
  ],
  "meta": { "cursor": null, "hasMore": false, "total": 1 }
}
```

***

## Create API key

```
POST /v1/projects/:projectId/keys
```

**Request body:**

```json theme={null}
{
  "name": "ci-deploy",
  "scopes": ["deployments:write", "servers:read"],
  "expiresAt": "2027-01-15T10:00:00Z"
}
```

| Field       | Type      | Required | Description                                                                   |
| ----------- | --------- | -------- | ----------------------------------------------------------------------------- |
| `name`      | string    | ✓        | Human-readable label                                                          |
| `scopes`    | string\[] | ✓        | List of [permission scopes](/getting-started/authentication#available-scopes) |
| `expiresAt` | ISO 8601  | —        | Expiry date; omit for non-expiring                                            |

**Response `201`:**

```json theme={null}
{
  "data": {
    "id": "key_abc123",
    "name": "ci-deploy",
    "key": "ezf_live_xxxxxxxxxxxxxxxxxxxx",
    "prefix": "ezf_live_",
    "scopes": ["deployments:write", "servers:read"],
    "projectId": "proj_abc123",
    "createdAt": "2026-01-15T10:00:00Z",
    "expiresAt": "2027-01-15T10:00:00Z",
    "lastUsedAt": null
  }
}
```

<Warning>
  The `key` field is only returned once, at creation time. Store it securely — it cannot be retrieved again.
</Warning>

***

## Delete API key

```
DELETE /v1/keys/:keyId
```

Immediately revokes the key. Any requests using it will receive a `401`.

**Response `204`:** No content.