OAuth2 Authorization Code Flow — Bkmark Integration Guide

Use the OAuth2 Authorization Code flow when you are building an application that acts on behalf of Bkmark users — a browser extension, a third-party integration, a mobile app, or a Zapier-style automation. The user grants your application specific permissions, and Bkmark issues your app a short-lived access token and a longer-lived refresh token. Your app never sees the user’s credentials. This flow follows RFC 6749 and supports PKCE (RFC 7636). PKCE is recommended for all clients and required for public clients such as single-page applications and mobile apps.

Getting OAuth2 Credentials

Before you can start the flow, register your application to receive a client_id and client_secret. Go to Settings → Developer → OAuth2 Clients in your Bkmark account and create a new client. You will need to provide:

A display name for your application
One or more allowed redirect URIs (exact match required)
The scopes your application plans to request

The Authorization Flow

Revoking Tokens

When a user disconnects your application, revoke their refresh token so Bkmark can clean up the session and the token can no longer be used:

curl -X POST https://api.bkmark.it/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..." \
  -d "token_type_hint=refresh_token" \
  -d "client_id=bk_your_client_id" \
  -d "client_secret=your_client_secret"

string

required

The access token or refresh token to revoke.

string

access_token or refresh_token. Optional but helps Bkmark look up the token faster.

string

required

Your application’s client ID.

string

required

Your application’s client secret.

This endpoint always returns 200 OK per RFC 7009, even if the token was already expired or revoked.

Token Introspection

To check whether a token is still active — for example, before making a batch of API calls — query the introspection endpoint:

curl https://api.bkmark.it/oauth/token-info \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Active token response:

{
  "active": true,
  "scope": "bookmarks:read bookmarks:write",
  "client_id": "bk_your_client_id",
  "user_id": "usr_01hq8p2z3kxv7m4n9rbt5c6d",
  "token_type": "Bearer",
  "expires_at": "2025-06-01T15:00:00.000Z",
  "created_at": "2025-06-01T14:00:00.000Z"
}

Expired or revoked token response:

{
  "active": false
}

boolean

true if the token is valid and has not expired or been revoked.

string

Space-separated scopes granted to this token.

string

The client ID that was issued this token.

string

The Bkmark user ID this token acts on behalf of.

string (ISO 8601)

UTC timestamp when the access token expires.

Security Checklist

Review this checklist before shipping your integration to production.

Never expose your client_secret in client-side JavaScript, mobile app binaries, or source control.
Always validate state in the callback before processing the authorization code.
Use PKCE for SPAs and mobile apps, which cannot keep a client_secret confidential.
Store tokens securely — use encrypted storage or a secrets manager, never cookies without HttpOnly/Secure flags or localStorage.
Implement automatic token refresh so users aren’t interrupted when access tokens expire.
Revoke tokens on disconnect — always call POST /oauth/revoke when a user unlinks your app.
Request only the scopes you need — see the Scopes reference for guidance on minimal scope sets.

Overview

Endpoints

OAuth2

OAuth2 Authorization Code Flow — Bkmark Integration Guide

Getting OAuth2 Credentials

The Authorization Flow

Revoking Tokens

Token Introspection

Security Checklist

​Getting OAuth2 Credentials

​The Authorization Flow

​Revoking Tokens

​Token Introspection

​Security Checklist

Getting OAuth2 Credentials

The Authorization Flow

Revoking Tokens

Token Introspection

Security Checklist