API keys API

These endpoints manage the API keys attached to your account. They require a **Clerk session JWT** (not an `sf_…` token) — `sf_…` tokens cannot mint or revoke other keys.

The dashboard's [/settings/api-keys](/settings/api-keys) page wraps these endpoints visually.

## `GET /me/keys`

List all keys for the signed-in user.

```ts
ApiKeyRow[] = {
  id:        string;          // ak_…
  userId:    string | null;
  name:      string | null;
  active:    boolean;         // false after revocation
  createdAt: string;          // ISO
  keyTail:   string;          // last 4 chars of the token, for display
}[]
```

Key hashes and plaintext values are **never** included — they're hashed at rest.

## `POST /me/keys`

Create a new key.

```
POST /me/keys
Authorization: Bearer <Clerk JWT>
Content-Type:  application/json

{ "name": "ci-runner" }   // optional, trimmed; null if empty
```

Response includes the plaintext **once**:

```ts
{
  key: {
    id: string; // ak_…
    userId: string | null;
    name: string | null;
    active: true;
    createdAt: string;
    keyTail: string;
  };
  plaintext: string;        // sf_… — copy now, it's never returned again
}
```

Lose the plaintext → revoke and create a new one. There is no recovery.

## `PATCH /me/keys/:id`

Rename a key with `{ "name": "ci-runner" }`. The name is trimmed; omitted or empty names become null. Returns HTTP 200 with the complete safe key row, in the same shape as a list entry. A missing or foreign key returns `404 NOT_FOUND`.

## `DELETE /me/keys/:id`

Deactivate a key. Returns HTTP 200 with the complete safe row, including `active: false`; a missing or foreign key returns `404 NOT_FOUND`.

```text
DELETE /me/keys/ak_example
Authorization: Bearer <Clerk JWT>
```

```json
{
  "id": "ak_example",
  "userId": "user_example",
  "name": "ci-runner",
  "active": false,
  "createdAt": "2026-09-25T00:00:00.000Z",
  "keyTail": "abcd"
}
```

Revoked keys remain in `GET /me/keys`, and existing jobs still reference them. Subsequent requests using the revoked plaintext return `401 UNAUTHENTICATED`. All failures use [structured errors](/docs/api/errors).

## `GET /me`

Returns the complete current User row to its signed-in owner, including identity, email, plan and billing reference. API keys cannot access this account endpoint.

Markdown agents.txt

These endpoints manage the API keys attached to your account. They require a Clerk session JWT (not an sf_… token) — sf_… tokens cannot mint or revoke other keys.

The dashboard’s /settings/api-keys page wraps these endpoints visually.

`GET /me/keys`

List all keys for the signed-in user.

ApiKeyRow[] = {
  id:        string;          // ak_…
  userId:    string | null;
  name:      string | null;
  active:    boolean;         // false after revocation
  createdAt: string;          // ISO
  keyTail:   string;          // last 4 chars of the token, for display
}[]

Key hashes and plaintext values are never included — they’re hashed at rest.

`POST /me/keys`

Create a new key.

POST /me/keys
Authorization: Bearer <Clerk JWT>
Content-Type:  application/json

{ "name": "ci-runner" }   // optional, trimmed; null if empty

Response includes the plaintext once:

{
  key: {
    id: string; // ak_…
    userId: string | null;
    name: string | null;
    active: true;
    createdAt: string;
    keyTail: string;
  };
  plaintext: string;        // sf_… — copy now, it's never returned again
}

Lose the plaintext → revoke and create a new one. There is no recovery.

`PATCH /me/keys/:id`

Rename a key with { "name": "ci-runner" }. The name is trimmed; omitted or empty names become null. Returns HTTP 200 with the complete safe key row, in the same shape as a list entry. A missing or foreign key returns 404 NOT_FOUND.

`DELETE /me/keys/:id`

Deactivate a key. Returns HTTP 200 with the complete safe row, including active: false; a missing or foreign key returns 404 NOT_FOUND.

DELETE /me/keys/ak_example
Authorization: Bearer <Clerk JWT>

{
  "id": "ak_example",
  "userId": "user_example",
  "name": "ci-runner",
  "active": false,
  "createdAt": "2026-09-25T00:00:00.000Z",
  "keyTail": "abcd"
}

Revoked keys remain in GET /me/keys, and existing jobs still reference them. Subsequent requests using the revoked plaintext return 401 UNAUTHENTICATED. All failures use structured errors.

`GET /me`

Returns the complete current User row to its signed-in owner, including identity, email, plan and billing reference. API keys cannot access this account endpoint.