Managing Bkmark API Keys for Programmatic Access Control

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.

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.

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.

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".

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.

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".

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):

{
  "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"
}

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.

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.

curl https://api.bkmark.it/api/v1/api-keys \
  -H "Authorization: Bearer bk_yourkey"

Response (200 OK):

{
  "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"
    }
  ]
}

string

Unique identifier for the API key. Use this ID to update or revoke the key.

string

The display name you assigned when creating the key.

string

The first 11 characters of the key (bk_ + 8 hex chars), for identification purposes.

string[]

The list of scopes currently granted to this key.

string | null

ISO 8601 timestamp of the most recent authenticated request made with this key, or null if the key has never been used.

string | null

ISO 8601 timestamp when the key expires, or null if the key has no expiry.

string

ISO 8601 timestamp when the key was created.

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.

string

A new display name for the key (1–100 characters).

string[]

A new set of scopes. Replaces the existing scopes entirely — include all scopes you want the key to have after the update.

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.

curl -X DELETE https://api.bkmark.it/api/v1/api-keys/01J2K8M4N5P6Q7R8S9T0U1V2W3 \
  -H "Authorization: Bearer bk_yourkey"

Response (200 OK):

{
  "message": "API key revoked"
}

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.

Overview

Endpoints

OAuth2

Managing Bkmark API Keys for Programmatic Access Control

Key Format

Available Scopes

Create an API Key

List API Keys

Update an API Key

Revoke an API Key

​Key Format

​Available Scopes

​Create an API Key

​List API Keys

​Update an API Key

​Revoke an API Key

Key Format

Available Scopes

Create an API Key

List API Keys

Update an API Key

Revoke an API Key