Authentication

All Bkper API access uses OAuth 2.0 with the email scope. The approach depends on your environment.

CLI and Node.js scripts

The simplest path. The CLI handles the OAuth flow and stores credentials locally.

bkper auth login

Then use getOAuthToken() as the auth provider for bkper-js:

import { Bkper } from 'bkper-js';
import { getOAuthToken } from 'bkper';

Bkper.setConfig({
    oauthTokenProvider: async () => getOAuthToken(),
});

This works for CLI scripts, Node.js automations, and local development of platform apps.

Browser with an access token

For any browser environment, use bkper-js directly with a valid access token via CDN — no build tools required, works on any domain:

<script src="https://cdn.jsdelivr.net/npm/bkper-js@2/dist/bkper.min.js"></script>
<script>
    const { Bkper } = bkperjs;

    async function listBooks(token) {
        Bkper.setConfig({
            oauthTokenProvider: async () => token,
        });
        const bkper = new Bkper();
        return await bkper.getBooks();
    }

    // Example: prompt for a token and list books
    document.getElementById('go').addEventListener('click', async () => {
        const token = document.getElementById('token').value;
        const books = await listBooks(token);
        document.getElementById('output').textContent =
            books.map(b => b.getName()).join('\n');
    });
</script>

<input id="token" placeholder="Paste your access token" />
<button id="go">List Books</button>
<pre id="output"></pre>

Get an access token via the Bkper CLI:

bkper auth login   # one-time setup
bkper auth token   # prints a token (valid for 1 hour)

Access tokens are automatically refreshed by the CLI and SDKs. When using a token directly (e.g. in a <script> tag or with curl), run bkper auth token again to get a fresh one.

Web applications on the Bkper Platform

Note

@bkper/web-auth only works on *.bkper.app subdomains. Its session cookies are scoped to the .bkper.app domain and will not work on any other domain. For apps on other domains, use the Browser with an access token approach instead.

For apps hosted on *.bkper.app subdomains, use the @bkper/web-auth SDK:

import { Bkper } from 'bkper-js';
import { BkperAuth } from '@bkper/web-auth';

const auth = new BkperAuth({
    onLoginSuccess: () => initializeApp(),
    onLoginRequired: () => showLoginButton(),
});
await auth.init();

Bkper.setConfig({
    oauthTokenProvider: async () => auth.getAccessToken(),
});

On the Bkper Platform, OAuth is pre-configured — no client IDs, redirect URIs, or consent screens to set up. Just use auth.getAccessToken() and the platform handles the rest.

See the @bkper/web-auth API Reference for the full SDK documentation.

Google Apps Script

Authentication is handled automatically by the Apps Script runtime. The bkper-gs library uses the built-in OAuth token:

function listBooks() {
    var books = BkperApp.getBooks();
    books.forEach(function (book) {
        Logger.log(book.getName());
    });
}

No additional authentication setup is needed. See Apps Script Development for library setup.

Direct API calls

For any language or platform, send a Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

The quickest way to get a token is via the CLI:

bkper auth token

Tokens expire after 1 hour. The CLI and SDKs handle refresh automatically; for direct usage, run the command again.

For custom OAuth 2.0 implementations, see the Google OAuth2 documentation:

• Server-side Web Apps
• JavaScript Web Apps
• Mobile and Desktop Apps

Event handler authentication

When Bkper calls your event handler’s webhook URL, it sends:

• bkper-oauth-token — An OAuth access token of the user who installed the app. Use this to call the API back on behalf of the user.
• bkper-agent-id — The app’s agent identifier.

On the Bkper Platform, these headers are handled automatically. For self-hosted setups:

• Cloud Functions — The call comes from bkper-hrd@appspot.gserviceaccount.com with the user’s OAuth token in the header.
• Generic webhooks — The call is signed with a JWT token using the Service to Function method.

Note

The development endpoint (webhookUrlDev) does not receive OAuth tokens. During local development on the Bkper Platform, the auth middleware in vite.config.ts handles token refresh for the client, using the CLI’s stored credentials. For self-hosted setups, you need to authenticate locally.

API keys (optional)

API keys are not required for authentication. They provide dedicated quota and project-level usage tracking.

If not provided, requests use a shared managed quota via the Bkper API proxy. The default shared quota is 60 requests per minute.

Bkper.setConfig({
    oauthTokenProvider: async () => getOAuthToken(),
    apiKeyProvider: async () => process.env.BKPER_API_KEY,
});

See Direct API Usage for API key setup instructions.