# API Keys

## Create API key

```
POST /api/v1/api-keys
```

Creates a new API key for the authenticated user.

### Request body

```json
{
  "name": "My integration"
}
```

| Field  | Required | Description                                 |
| ------ | -------- | ------------------------------------------- |
| `name` | Yes      | Display name for the key (1–100 characters) |

### Response

```json
{
  "data": {
    "id": "key_uuid",
    "name": "My integration",
    "prefix": "rm_abc123",
    "key": "rm_abc123def456...",
    "created_at": "2025-09-19T15:00:00.000Z"
  }
}
```

{% hint style="warning" %}
The `key` field is returned **only once** at creation time. Store it securely — it cannot be retrieved again. Only the `prefix` (first 8 characters) is shown in subsequent requests.
{% endhint %}

***

## List API keys

```
GET /api/v1/api-keys
```

Returns all API keys for the authenticated user. The full key value is never returned after creation.

### Response

```json
{
  "data": [
    {
      "id": "key_uuid",
      "name": "My integration",
      "prefix": "rm_abc123",
      "created_at": "2025-09-19T15:00:00.000Z",
      "last_used_at": "2025-09-20T10:30:00.000Z",
      "is_revoked": false
    }
  ]
}
```

***

## Revoke API key

```
DELETE /api/v1/api-keys/:id
```

Permanently revokes an API key. Requests using this key will immediately fail with `INVALID_API_KEY`.

### Response

```json
{
  "data": { "success": true }
}
```

### Error codes

| Code                | HTTP Status | Meaning                                       |
| ------------------- | ----------- | --------------------------------------------- |
| `API_KEY_NOT_FOUND` | 404         | Key does not exist or belongs to another user |
| `ALREADY_REVOKED`   | 400         | Key was already revoked                       |