Direct API Usage

The Bkper REST API is the universal interface for interacting with Bkper Books. Every library and tool — bkper-js, bkper-gs, the CLI — is built on top of it. You can use it directly from any language or platform.

Base URL

https://api.bkper.app

All API calls use this endpoint:

• https://api.bkper.app/v5/books — List books
• https://api.bkper.app/v5/books/{bookId} — Get a specific book

Specifications

The API is built on OpenAPI and Google API Discovery specifications:

• OpenAPI specification
• Google API Discovery document

You can use these specifications to generate client libraries with tools like OpenAPI generator or Google APIs code generator in the language of your choice.

For TypeScript, we maintain an updated type definitions package:

• @bkper/bkper-api-types

Getting started

To use the API, you need a valid OAuth2 access token. No API key is required — the Bkper API proxy provides a managed key with shared quota.

CLI / Node.js

Use bkper-js with the CLI for authentication:

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

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

const bkper = new Bkper();
const books = await bkper.getBooks();

First authenticate via CLI: bkper auth login

Web applications

Use bkper-js with @bkper/web-auth for browser authentication:

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

const auth = new BkperAuth({ onLoginSuccess: () => initApp() });
await auth.init();

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

const bkper = new Bkper();
const books = await bkper.getBooks();

Google Apps Script

Use bkper-gs:

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

Direct HTTP calls

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

Authorization: Bearer YOUR_ACCESS_TOKEN

For details on obtaining tokens, see Authentication.

API Explorer

The REST API Explorer lets you browse endpoints, inspect payload formats, and try the API live:

Open API Explorer

---

Custom API key

For dedicated quota and project-level usage tracking, you can optionally configure your own API key:

1. Join bkper@googlegroups.com to unlock access to enable the API on your project
2. Create a new GCP project, or select an existing one
3. Enable the Bkper API in the Google Cloud Console
4. Create an API key
   • Add API Restrictions to app.bkper.com API only

Send your API key in the bkper-api-key HTTP header:

bkper-api-key: YOUR_API_KEY

Note

API keys are for project identification and quota management only, not for authentication. Do not store API keys in your code. See securing an API key best practices.

Tip

For Google Apps Script, you can store the API key in the Script Properties. To store it, open the online editor, File > Project properties > Script properties.

Metrics

With your own API key, you can view detailed metrics on the GCP Console for your project’s API calls:

The metrics dashboard provides information about endpoint calls, latency, and errors — a good overview of your integration’s health.

Quota

The quotas dashboard provides details of the current default and quota exceeded errors.

The default shared quota is 60 requests per minute. If you need higher limits with your own API key, please get in touch so we can discuss your case.