# API Keys

Create and manage API keys for programmatic access to the Keychains.dev API. Keys expire after a maximum of 30 days and can be revoked at any time.

## POST `/api/api-keys`

Create a new API key. The raw key value is returned only once in the response — save it immediately.

**Authentication**  
Session cookie or Machine JWT (not API key)

### Request Body (JSON)

| Field         | Type    | Description                                                                           |
|---------------|---------|---------------------------------------------------------------------------------------|
| name\*       | string  | Human-readable name for the key                                                      |
| expirySeconds | integer | Expiry in seconds (max 2,592,000 = 30 days). Defaults to 30 days.                   |

### Response

```json
{
  "key": "kc_abc123...",
  "id": "ak_xyz789",
  "name": "CI Pipeline",
  "keyPrefix": "kc_abc123...",
  "createdAt": "2026-02-17T10:00:00.000Z",
  "expiresAt": "2026-03-19T10:00:00.000Z"
}
```

### Examples

#### curl

```bash
curl -X POST https://keychains.dev/api/api-keys \
  -H "Authorization: Bearer <session-or-machine-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "expirySeconds": 604800}'
```

#### Node.js

```javascript
const res = await fetch("https://keychains.dev/api/api-keys", {
  method: "POST",
  headers: {
    Authorization: "Bearer <session-or-machine-jwt>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "CI Pipeline", expirySeconds: 604800 }),
});
const { key, id } = await res.json();
// Save `key` — it won't be shown again
```

## GET `/api/api-keys`

List all API keys for the authenticated user. Returns key metadata (not the raw key values).

**Authentication**  
Session cookie, Machine JWT, or API key

### Response

```json
{
  "keys": [
    {
      "id": "ak_xyz789",
      "name": "CI Pipeline",
      "keyPrefix": "kc_abc123...",
      "createdAt": "2026-02-17T10:00:00.000Z",
      "expiresAt": "2026-03-19T10:00:00.000Z",
      "lastUsedAt": "2026-02-17T14:30:00.000Z"
    }
  ]
}
```

### Examples

#### curl

```bash
curl https://keychains.dev/api/api-keys \
  -H "Authorization: Bearer kc_your_api_key"
```

#### Node.js

```javascript
const res = await fetch("https://keychains.dev/api/api-keys", {
  headers: { Authorization: "Bearer kc_your_api_key" },
});
const { keys } = await res.json();
```

## DELETE `/api/api-keys/:keyId`

Revoke an API key. The key will immediately stop working for authentication.

**Authentication**  
Session cookie or Machine JWT (not API key)

### Response

```json
{
  "success": true,
  "id": "ak_xyz789"
}
```

### Examples

#### curl

```bash
curl -X DELETE https://keychains.dev/api/api-keys/ak_xyz789 \
  -H "Authorization: Bearer <session-or-machine-jwt>"
```

#### Node.js

```javascript
await fetch("https://keychains.dev/api/api-keys/ak_xyz789", {
  method: "DELETE",
  headers: { Authorization: "Bearer <session-or-machine-jwt>" },
});
```

## CLI Usage

You can also manage API keys from the Keychains CLI:

### Create a key

```bash
keychains api-key create --name "My Script" --expiry-days 7
```

### List all keys

```bash
keychains api-key ls
```

### Revoke a key

```bash
keychains api-key revoke ak_xyz789
```

[API Overview](/content/docs/api/index.html) [Connections](/content/docs/api/connections/index.html)