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

# Managing Bkmark API Keys for Programmatic Access Control

> Create, list, update, and revoke Bkmark API keys to authenticate personal automation scripts and tools without the full OAuth2 flow.

API keys give you a simple, long-lived credential to authenticate against your own Bkmark account. Unlike OAuth2 tokens, which expire in an hour and require a refresh flow, an API key remains valid until you revoke it or it reaches an optional expiry date you set at creation time. They are the right tool for personal scripts, CLI tools, and automation pipelines where you are always acting on your own data.

<Note>
  API keys are available on the **Pro** and **Team** plans. If you are on the free plan, upgrade your account before trying to create a key. You can also manage keys in the Bkmark web app under **Settings → Security → API Keys**.
</Note>

## Key Format

Every API key begins with the `bk_` prefix followed by 32 hexadecimal characters (16 random bytes), for example:

```
bk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
```

The full raw key is **only returned once** — at the moment you create it. Bkmark stores only a securely hashed value of the key and an 11-character prefix (e.g. `bk_a1b2c3d4`) for identification in list responses. If you lose the key, you must revoke it and create a new one.

## Available Scopes

Each API key carries a set of scopes that define exactly what it is allowed to do. Assign the minimum scopes your use case requires.

| Scope             | Access granted                       |
| ----------------- | ------------------------------------ |
| `bookmarks:read`  | Read bookmarks and their metadata    |
| `bookmarks:write` | Create, update, and delete bookmarks |
| `tags:read`       | Read tags                            |
| `tags:write`      | Create, update, and delete tags      |
| `groups:read`     | Read groups and their members        |
| `groups:write`    | Create, update, and delete groups    |
| `search:read`     | Run bookmark searches                |

## Create an API Key

Send a `POST` request to `/api/v1/api-keys` with a display name, the scopes you need, and an optional expiry date.

<ParamField body="name" type="string" required>
  A human-readable label for the key (1–100 characters). Use something descriptive so you can identify the key's purpose later, for example `"CI deploy script"` or `"Home server backup"`.
</ParamField>

<ParamField body="scopes" type="string[]" required>
  One or more scopes to grant. Must contain at least one value. Valid values: `bookmarks:read`, `bookmarks:write`, `tags:read`, `tags:write`, `groups:read`, `groups:write`, `search:read`.
</ParamField>

<ParamField body="expiresAt" type="string (ISO 8601 datetime)">
  An optional expiry date-time in ISO 8601 format. If omitted, the key never expires. Example: `"2026-01-01T00:00:00.000Z"`.
</ParamField>

```bash theme={null}
curl -X POST https://api.bkmark.it/api/v1/api-keys \
  -H "Authorization: Bearer bk_existingkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home server backup",
    "scopes": ["bookmarks:read", "tags:read"],
    "expiresAt": "2026-01-01T00:00:00.000Z"
  }'
```

**Response (`201 Created`):**

```json theme={null}
{
  "id": "01J2K8M4N5P6Q7R8S9T0U1V2W3",
  "name": "Home server backup",
  "key": "bk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "keyPrefix": "bk_a1b2c3d4",
  "scopes": ["bookmarks:read", "tags:read"],
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "createdAt": "2024-11-01T09:00:00.000Z"
}
```

<Warning>
  Copy the `key` value from this response and store it somewhere safe immediately — a password manager or secrets vault. Bkmark will **never show you the full key again**. If you lose it, revoke the key and create a new one.
</Warning>

## List API Keys

Retrieve all API keys associated with your account. The response includes metadata but **never** the raw key value — only the short `keyPrefix` for identification.

```bash theme={null}
curl https://api.bkmark.it/api/v1/api-keys \
  -H "Authorization: Bearer bk_yourkey"
```

**Response (`200 OK`):**

```json theme={null}
{
  "data": [
    {
      "id": "01J2K8M4N5P6Q7R8S9T0U1V2W3",
      "name": "Home server backup",
      "keyPrefix": "bk_a1b2c3d4",
      "scopes": ["bookmarks:read", "tags:read"],
      "lastUsedAt": "2024-11-15T14:32:00.000Z",
      "expiresAt": "2026-01-01T00:00:00.000Z",
      "createdAt": "2024-11-01T09:00:00.000Z"
    },
    {
      "id": "01J2K8M4N5P6Q7R8S9T0U1V2W4",
      "name": "CI deploy script",
      "keyPrefix": "bk_f9e8d7c6",
      "scopes": ["bookmarks:read", "bookmarks:write"],
      "lastUsedAt": null,
      "expiresAt": null,
      "createdAt": "2024-11-10T11:00:00.000Z"
    }
  ]
}
```

<ResponseField name="id" type="string">
  Unique identifier for the API key. Use this ID to update or revoke the key.
</ResponseField>

<ResponseField name="name" type="string">
  The display name you assigned when creating the key.
</ResponseField>

<ResponseField name="keyPrefix" type="string">
  The first 11 characters of the key (`bk_` + 8 hex chars), for identification purposes.
</ResponseField>

<ResponseField name="scopes" type="string[]">
  The list of scopes currently granted to this key.
</ResponseField>

<ResponseField name="lastUsedAt" type="string | null">
  ISO 8601 timestamp of the most recent authenticated request made with this key, or `null` if the key has never been used.
</ResponseField>

<ResponseField name="expiresAt" type="string | null">
  ISO 8601 timestamp when the key expires, or `null` if the key has no expiry.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the key was created.
</ResponseField>

## Update an API Key

You can rename a key or change its scopes at any time with a `PATCH` request. Include only the fields you want to change.

<ParamField body="name" type="string">
  A new display name for the key (1–100 characters).
</ParamField>

<ParamField body="scopes" type="string[]">
  A new set of scopes. Replaces the existing scopes entirely — include all scopes you want the key to have after the update.
</ParamField>

```bash theme={null}
curl -X PATCH https://api.bkmark.it/api/v1/api-keys/01J2K8M4N5P6Q7R8S9T0U1V2W3 \
  -H "Authorization: Bearer bk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home server backup (read-only)",
    "scopes": ["bookmarks:read", "tags:read", "groups:read"]
  }'
```

The response returns the full updated key object (without the raw key value).

## Revoke an API Key

Send a `DELETE` request to permanently revoke a key. Any subsequent requests using that key will immediately receive a `401 Unauthorized` response.

```bash theme={null}
curl -X DELETE https://api.bkmark.it/api/v1/api-keys/01J2K8M4N5P6Q7R8S9T0U1V2W3 \
  -H "Authorization: Bearer bk_yourkey"
```

**Response (`200 OK`):**

```json theme={null}
{
  "message": "API key revoked"
}
```

<Tip>
  Revoke keys you no longer use — for example, when a project ends, a script is retired, or a team member with access to the key leaves. You can always create a new key with the right scopes for your next project.
</Tip>