Skip to main content
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.
ScopeAccess granted
bookmarks:readRead bookmarks and their metadata
bookmarks:writeCreate, update, and delete bookmarks
tags:readRead tags
tags:writeCreate, update, and delete tags
groups:readRead groups and their members
groups:writeCreate, update, and delete groups
search:readRun 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.
​
name
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".
​
scopes
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.
​
expiresAt
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"
    }
  ]
}
​
id
string
Unique identifier for the API key. Use this ID to update or revoke the key.
​
name
string
The display name you assigned when creating the key.
​
keyPrefix
string
The first 11 characters of the key (bk_ + 8 hex chars), for identification purposes.
​
scopes
string[]
The list of scopes currently granted to this key.
​
lastUsedAt
string | null
ISO 8601 timestamp of the most recent authenticated request made with this key, or null if the key has never been used.
​
expiresAt
string | null
ISO 8601 timestamp when the key expires, or null if the key has no expiry.
​
createdAt
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.
​
name
string
A new display name for the key (1–100 characters).
​
scopes
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.