OAuth2 Scopes — Permissions Reference

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

Scope	What it allows	Endpoints unlocked
`bookmarks:read`	View, search, and export bookmarks	`GET /bookmarks`, `GET /bookmarks/:id`, `GET /bookmarks/export`, `GET /bookmarks/trash`, `GET /search`
`bookmarks:write`	Create, edit, delete, and import bookmarks	`POST /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:read`	View tags	`GET /tags`
`tags:write`	Create, rename, and delete tags	`POST /tags`, `PATCH /tags/:id`, `DELETE /tags/:id`
`groups:read`	View groups	`GET /groups`, `GET /groups/:id`
`groups:write`	Create, rename, and delete groups	`POST /groups`, `PATCH /groups/:id`, `DELETE /groups/:id`
`search:read`	Full-text search across bookmarks	`GET /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:

endpoint

List all bookmarks. Supports filtering by since, updatedSince, tags, and groups.

endpoint

Fetch a single bookmark by ID.

endpoint

Export all bookmarks as JSON.

endpoint

List soft-deleted bookmarks pending permanent deletion.

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:

endpoint

Save a new bookmark.

endpoint

Update a bookmark’s title, description, tags, groups, favorite status, or archived status.

endpoint

Soft-delete a bookmark (moves to trash).

endpoint

Replace all tags on a bookmark.

endpoint

Replace all group assignments for a bookmark.

endpoint

Apply a single action (tag, move, archive, favorite, delete, or export) to up to 500 bookmarks at once.

endpoint

Import bookmarks from a browser HTML export, Pocket, Raindrop, or a Bkmark JSON export.

endpoint

Restore a soft-deleted bookmark from trash.

`tags:read`

Grants read access to the user’s tag list.

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.

endpoint

Create a new tag.

endpoint

Rename a tag or change its color.

endpoint

Delete a tag (removes it from all bookmarks).

`groups:read`

Grants read access to the user’s groups (collections of bookmarks).

endpoint

List all groups.

endpoint

Fetch a single group and its metadata.

`groups:write`

Grants write access to create, rename, and delete groups.

endpoint

Create a new group.

endpoint

Rename a group or change its color.

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.

endpoint

Full-text search across bookmark titles, descriptions, and URLs.

Recommended Scope Sets

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:

Bkmark validates the Authorization: Bearer token.
Bkmark checks whether the token’s granted scopes include the scope required by the endpoint being called.
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.

Overview

Endpoints

OAuth2

OAuth2 Scopes — Permissions Reference — Bkmark API

Available Scopes

Scope Details

`bookmarks:read`

`bookmarks:write`

`tags:read`

`tags:write`

`groups:read`

`groups:write`

`search:read`

Recommended Scope Sets

Read-only

Bookmark manager

Full access

Scope Enforcement

​Available Scopes

​Scope Details

​bookmarks:read

​bookmarks:write

​tags:read

​tags:write

​groups:read

​groups:write

​search:read

​Recommended Scope Sets

​Read-only

​Bookmark manager

​Full access

​Scope Enforcement

Available Scopes

Scope Details

`bookmarks:read`

`bookmarks:write`

`tags:read`

`tags:write`

`groups:read`

`groups:write`

`search:read`

Recommended Scope Sets

Read-only

Bookmark manager

Full access

Scope Enforcement