Skip to content
Bkper
app.header.homeapp.header.docs

Authentication

How OAuth2 authentication works across all Bkper build environments: CLI token via getOAuthToken(), browser-based OAuth via @bkper/web-auth, automatic handling in Apps Script, and Bearer token authentication for direct REST API calls.

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.

Terminal window
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.

Web applications

For browser-based apps, 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

You can obtain a token through any of the methods above, or implement OAuth 2.0 directly. For custom implementations, see the Google OAuth2 documentation:

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.

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.