> ## Documentation Index
> Fetch the complete documentation index at: https://metacognition-fdc534de-master.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List, create, and revoke API keys

> List, create, and revoke long-lived API keys for your org.

## `GET /me/api-keys`

Lists keys for the current **org**, sorted by `created_at` descending. The response matches the `api_keys` field in `GET /me`.

```http theme={null}
GET /me/api-keys[?include_revoked=true]
Authorization: Bearer <access_token>
```

<ParamField query="include_revoked" type="boolean" default="false">
  When `true`, includes revoked keys (with non-null `revoked_at`).
</ParamField>

## `POST /me/api-keys`

Creates a new key. The plaintext value is returned **once**.

```http theme={null}
POST /me/api-keys
Authorization: Bearer <access_token>
Content-Type: application/json
```

### Body

```json theme={null}
{
  "name":   "laptop-dev",
  "scopes": ["*"]
}
```

<ParamField body="name" type="string">
  Optional human-readable label, max 64 chars.
</ParamField>

<ParamField body="scopes" type="array[string]" default="[&#x22;*&#x22;]">
  Permission scopes for the new key. Default `["*"]` means full access. Scoped keys (e.g. `["read"]`) are reserved for future use.
</ParamField>

### Response — `201`

<ResponseField name="api_key" type="string">
  Plaintext key. Store immediately.
</ResponseField>

<ResponseField name="key" type="object">
  Metadata for the key, including id, prefix, display\_id, name, scopes, and timestamps.
</ResponseField>

```json theme={null}
{
  "api_key": "tex_live_eGpnAyArDoncUaK9r-sT9um__jvKEZutqpbVwsS4iJw",
  "key": {
    "id": "30a820b9-11b6-4a54-93fc-0a682c167476",
    "prefix": "tex_live_",
    "display_id": "eGpnAyAr",
    "name": "laptop-dev",
    "scopes": ["*"],
    "is_active": true,
    "created_at": "2026-05-08T09:57:02.363742",
    "last_used_at": null,
    "revoked_at": null
  }
}
```

## `DELETE /me/api-keys/{id}`

Revokes a key. Returns `204 No Content`.

```http theme={null}
DELETE /me/api-keys/{id}
Authorization: Bearer <access_token>
```

<ParamField path="id" type="string" required>
  The key's UUID (the `id` field, not the prefix or display\_id).
</ParamField>

<Warning>
  Revocation is **irreversible.** Existing JWTs created from a revoked key keep working until they expire, up to 24h after revocation.
</Warning>

## Examples

<CodeGroup>
  ```bash cURL - list, mint, revoke theme={null}
  # List active keys
  curl -H "Authorization: Bearer $JWT" \
    https://api.getmetacognition.com/me/api-keys

  # Mint a new one
  curl -X POST -H "Authorization: Bearer $JWT" \
    -H 'content-type: application/json' \
    -d '{"name":"production"}' \
    https://api.getmetacognition.com/me/api-keys

  # Revoke
  curl -X DELETE -H "Authorization: Bearer $JWT" \
    https://api.getmetacognition.com/me/api-keys/a1247653-9646-4f32-b04f-72d2c0f5355b
  ```

  ```python Python theme={null}
  import httpx

  H = {"Authorization": f"Bearer {jwt}"}
  api = "https://api.getmetacognition.com"

  # List
  keys = httpx.get(f"{api}/me/api-keys", headers=H).json()

  # Mint
  new = httpx.post(f"{api}/me/api-keys", headers=H, json={"name": "production"}).json()
  plaintext = new["api_key"]   # save this

  # Revoke
  httpx.delete(f"{api}/me/api-keys/{key_id}", headers=H)
  ```
</CodeGroup>

## Operational tips

* One key per environment. Mint `production`, `staging`, and `local-dev` separately.
* Alert if a key has not been used in 30 days. It may be abandoned.
* Do not share keys across services. Give each service its own key so revocation is narrow.