Authentication
API token management, scopes, and security
All API requests require a Bearer token in the Authorization header.
Authorization: Bearer bkl_your_token_hereToken Format
Tokens use the bkl_ prefix followed by 64 hex characters (256-bit entropy):
bkl_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4Tokens are shown only once at creation. Only the SHA-256 hash is stored server-side.
Requirements
- API access requires a Pro plan or higher
- Each user can have up to 10 active tokens
- Tokens can optionally have an expiration date
Scopes
Scopes control what a token can do. When creating a token, select the scopes you need.
| Scope | Description |
|---|---|
bookmarks:read | Read bookmarks, search, stats, domains |
bookmarks:write | Create, update, favorite, move, soft-delete bookmarks |
collections:read | List and view collections |
collections:write | Create, update, soft-delete collections |
tags:read | List tags |
tags:write | Create, rename, delete, merge tags; add/remove tags on bookmarks |
import | Import bookmarks (opt-in) |
export | Export your library (opt-in) |
destructive | Permanent delete, empty trash (opt-in) |
Default scopes (when no specific selection): all except import, export, and destructive.
Write implies read -- a token with bookmarks:write can also perform bookmarks:read operations.
Token Management
Create a Token
Create tokens from your dashboard under Settings > API Tokens.
Verify a Token
Check if an existing token is valid:
curl https://api.bookmark.land/v1/auth/verify \
-H "Authorization: Bearer bkl_your_token_here"Revoke a Token
Revoking is immediate. The token stops working instantly.
Token Expiration
Tokens can optionally expire. Expired tokens return a TOKEN_EXPIRED error (401).
Error Responses
| Code | Status | Description |
|---|---|---|
MISSING_TOKEN | 401 | No Authorization header or missing Bearer prefix |
INVALID_TOKEN | 401 | Token doesn't match any active token |
TOKEN_REVOKED | 401 | Token has been revoked |
TOKEN_EXPIRED | 401 | Token has passed its expiration date |
SCOPE_REQUIRED | 403 | Token lacks the required scope for this endpoint |
API_ACCESS_PRO_REQUIRED | 403 | API access requires a Pro plan or higher |
Security Best Practices
- Never share tokens in client-side code, public repos, or logs
- Use minimal scopes -- only grant what you need
- Set expiration dates for tokens used in CI/CD or temporary integrations
- Rotate tokens regularly -- revoke old tokens and create new ones
- Use separate tokens for different integrations so you can revoke individually