Skip to main content
Every request to the Bkmark API must include valid credentials in the Authorization header. Bkmark supports two authentication methods depending on your use case: OAuth2 Bearer tokens for third-party integrations that act on behalf of users, and API keys for personal scripts or automation that act on your own account. Choose the method that fits your situation, and use the examples below to get started quickly.
Which method should you use?Use an OAuth2 Bearer token when you are building an integration or application that other Bkmark users will connect to. The OAuth2 flow lets users grant your app specific permissions without sharing their password, and they can revoke access at any time.Use an API key when you are writing personal scripts or automation that only need to access your own Bkmark account. API keys are simpler to set up but are tied to a single user and require a Pro or Team plan.

​
OAuth2 Bearer Token

OAuth2 Bearer tokens are the recommended authentication method for third-party integrations. You obtain a token by directing a user through the OAuth2 Authorization Code flow, after which you receive an access_token you can use in API requests. For a complete walkthrough of the authorization flow, including PKCE setup, token exchange, and refresh handling, see the OAuth2 Authorization page. Once you have an access token, include it in every request using the Authorization header: 
curl https://api.bkmark.it/api/v1/bookmarks \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"
Access tokens expire after 1 hour. Use your refresh token to obtain a new access token before the current one expires: 
curl -X POST https://api.bkmark.it/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=bk_your_client_id" \
  -d "client_secret=your_client_secret"

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh...",
  "scope": "bookmarks:read bookmarks:write tags:read"
}
Refresh tokens expire after 90 days and are single-use — each refresh response includes a new refresh token. Always store the latest refresh token and discard the old one immediately.

​
API Key

API keys let you authenticate against your own Bkmark account without going through the OAuth2 flow. They are ideal for automation scripts, CI pipelines, or local tooling. You generate API keys in Settings → Security → API Keys in the Bkmark web app, or via the API Keys endpoint. Use an API key with the same Authorization header format as a Bearer token: 
curl https://api.bkmark.it/api/v1/bookmarks \
  -H "Authorization: Bearer bk_yourkey" \
  -H "Accept: application/json"
API keys begin with the bk_ prefix, making them easy to identify in logs and secret scanners. Each key carries a set of scopes that restrict what it can do — for example, a key with only bookmarks:read cannot create or delete bookmarks. 
# Example: create a bookmark using an API key
curl -X POST https://api.bkmark.it/api/v1/bookmarks \
  -H "Authorization: Bearer bk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "title": "An Example Article",
    "tags": ["reading"]
  }'
See API Keys for instructions on creating keys, managing scopes, and revoking keys you no longer need.

​
Session Cookies

The Bkmark web application uses session cookies for its own authentication. Session cookies are not a supported authentication method for API requests — they are for internal use by the web app only. If you are building an integration, use OAuth2 or an API key instead.

​
Security Best Practices

  • Never expose credentials in client-side code, URLs, or logs. Treat tokens and API keys as secrets.
  • Request minimal scopes. Only ask for the permissions your integration actually needs.
  • Revoke credentials when they are no longer needed. Revoke OAuth2 refresh tokens when a user disconnects your app, and delete API keys for scripts you have retired.
  • Rotate API keys periodically. Generate a new key, update your configuration, and revoke the old key on a regular schedule.
  • Implement automatic token refresh. Proactively refresh OAuth2 access tokens before they expire to avoid disrupting your users.