Skip to main content
Scopes define exactly what your application can do on behalf of a user. When you redirect a user to the Bkmark authorization endpoint, you specify the scopes you need in the scope query parameter. The user sees a plain-language description of each permission on the consent screen and can approve or deny the request. Bkmark enforces scopes on every API request. If your token doesn’t carry the right scope for an endpoint, the API returns 403 Forbidden — even if the token is otherwise valid. This means you must request all the scopes you need upfront; you cannot silently expand them later without sending the user through the authorization flow again.
Request only the scopes your integration genuinely needs. Requesting excessive permissions makes the consent screen more alarming to users, reduces the likelihood they’ll approve, and increases your blast radius if a token is ever compromised. Follow the principle of least privilege.

​
Available Scopes

ScopeWhat it allowsEndpoints unlocked
bookmarks:readView, search, and export bookmarksGET /bookmarks, GET /bookmarks/:id, GET /bookmarks/export, GET /bookmarks/trash, GET /search
bookmarks:writeCreate, edit, delete, and import bookmarksPOST /bookmarks, PATCH /bookmarks/:id, DELETE /bookmarks/:id, POST /bookmarks/:id/tags, POST /bookmarks/:id/groups, POST /bookmarks/bulk, POST /bookmarks/import, POST /bookmarks/:id/restore
tags:readView tagsGET /tags
tags:writeCreate, rename, and delete tagsPOST /tags, PATCH /tags/:id, DELETE /tags/:id
groups:readView groupsGET /groups, GET /groups/:id
groups:writeCreate, rename, and delete groupsPOST /groups, PATCH /groups/:id, DELETE /groups/:id
search:readFull-text search across bookmarksGET /search
search:read is a subset of what bookmarks:read already covers — GET /search is accessible with either scope. Request search:read alone when your integration only needs search and should not be able to enumerate a user’s full bookmark list.

​
Scope Details

​
bookmarks:read

Grants read access to a user’s bookmarks, including the ability to export them and query trash. Endpoints:
​
GET /bookmarks
endpoint
List all bookmarks. Supports filtering by since, updatedSince, tags, and groups.
​
GET /bookmarks/:id
endpoint
Fetch a single bookmark by ID.
​
GET /bookmarks/export
endpoint
Export all bookmarks as JSON.
​
GET /bookmarks/trash
endpoint
List soft-deleted bookmarks pending permanent deletion.
​
GET /search
endpoint
Full-text search across bookmark titles, descriptions, and URLs.

​
bookmarks:write

Grants write access to create, modify, and delete bookmarks, plus bulk operations and import.
bookmarks:write does not imply bookmarks:read. If your app needs to read bookmarks it just created, request both scopes.
Endpoints:
​
POST /bookmarks
endpoint
Save a new bookmark.
​
PATCH /bookmarks/:id
endpoint
Update a bookmark’s title, description, tags, groups, favorite status, or archived status.
​
DELETE /bookmarks/:id
endpoint
Soft-delete a bookmark (moves to trash).
​
POST /bookmarks/:id/tags
endpoint
Replace all tags on a bookmark.
​
POST /bookmarks/:id/groups
endpoint
Replace all group assignments for a bookmark.
​
POST /bookmarks/bulk
endpoint
Apply a single action (tag, move, archive, favorite, delete, or export) to up to 500 bookmarks at once.
​
POST /bookmarks/import
endpoint
Import bookmarks from a browser HTML export, Pocket, Raindrop, or a Bkmark JSON export.
​
POST /bookmarks/:id/restore
endpoint
Restore a soft-deleted bookmark from trash.

​
tags:read

Grants read access to the user’s tag list.
​
GET /tags
endpoint
List all tags, including name, color, and bookmark count.

​
tags:write

Grants write access to create, rename, and delete tags.
tags:write does not imply tags:read. Request both if you need to read existing tags before creating new ones.
​
POST /tags
endpoint
Create a new tag.
​
PATCH /tags/:id
endpoint
Rename a tag or change its color.
​
DELETE /tags/:id
endpoint
Delete a tag (removes it from all bookmarks).

​
groups:read

Grants read access to the user’s groups (collections of bookmarks).
​
GET /groups
endpoint
List all groups.
​
GET /groups/:id
endpoint
Fetch a single group and its metadata.

​
groups:write

Grants write access to create, rename, and delete groups.
​
POST /groups
endpoint
Create a new group.
​
PATCH /groups/:id
endpoint
Rename a group or change its color.
​
DELETE /groups/:id
endpoint
Delete a group (bookmarks inside are not deleted).

​
search:read

Grants access to full-text search without exposing the full bookmark list. Use this when your integration only needs to let the user find bookmarks by keyword.
​
GET /search
endpoint
Full-text search across bookmark titles, descriptions, and URLs.
Choose the combination that matches your integration type. Copy the scope string directly into your authorization URL.

​
Read-only

bookmarks:read tags:read groups:read
Use for dashboards, analytics, bookmark viewers, and audit tools that only display data and never write anything back.

​
Bookmark manager

bookmarks:read bookmarks:write tags:read tags:write groups:read
Use for browser extensions, import/export tools, Zapier or Make actions that save new bookmarks, and apps that organize bookmarks with tags. Includes full bookmark read/write and tag read/write, but does not allow creating or deleting groups.

​
Full access

bookmarks:read bookmarks:write tags:read tags:write groups:read groups:write search:read
Use for fully-featured clients, backup and sync tools, and power-user automations that need complete control over a user’s Bkmark account.

​
Scope Enforcement

When your application makes an API request:
  1. Bkmark validates the Authorization: Bearer token.
  2. Bkmark checks whether the token’s granted scopes include the scope required by the endpoint being called.
  3. If the required scope is missing, Bkmark returns 403 Forbidden with an error body indicating which scope is needed.
{
  "error": "insufficient_scope",
  "error_description": "This endpoint requires the bookmarks:write scope.",
  "required_scope": "bookmarks:write"
}
Scopes are fixed at authorization time. If a user approved bookmarks:read but your app later needs bookmarks:write, you must send the user through the authorization flow again with the full set of scopes you need. You cannot silently add scopes to an existing token.
Check the scope field in the token exchange response (or call GET /oauth/token-info) to confirm which scopes were actually granted before making write calls. Users can grant a subset of what you requested.