> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bkmark.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating Bkmark API Requests with OAuth2 and API Keys

> Authorize Bkmark API requests using an OAuth2 Bearer token for third-party integrations or an API key for personal automation scripts and tools.

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.

<Note>
  **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.
</Note>

## 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](/api/oauth/authorization) page.

Once you have an access token, include it in every request using the `Authorization` header:

```bash theme={null}
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:

```bash theme={null}
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"
```

```json theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh...",
  "scope": "bookmarks:read bookmarks:write tags:read"
}
```

<Note>
  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.
</Note>

## 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](/api/api-keys).

Use an API key with the same `Authorization` header format as a Bearer token:

```bash theme={null}
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.

```bash theme={null}
# 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](/api/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.