API Keys, OpenAPI and the JavaScript Client

A custom member dashboard, a Zapier step or a nightly sync script needs to call your booking API without a person logged in. API keys give that server its own credential, limited to the permissions you pick, and you can revoke one at any time without touching anyone’s WordPress password.

API keys need Core Bookings 1.1.0 or later and the Developer API module. For the routes themselves, see REST API.

Create a Key

1. Turn on Developer API under Bookings → Settings → Modules. It is off by default.
2. Open Bookings → Settings → API keys (under Connections).
3. Fill in the form:
   • Name: where the key is used, such as “Member dashboard”.
   • Acts as: the manager or staff member the key works as.
   • Permissions: one or more scopes from the table below.
   • Expires: in 30, 90 or 365 days, or never. 90 days is the default.
4. Click Create API key and copy the key right away.

The full key (it starts with cbk_) is shown once. Core Bookings stores only a fingerprint of it, so a lost key cannot be recovered. Revoke it and create a new one.

Pick the Right Permissions

Permission	What the key can do
read	Read services, availability, prices, bookings, customers and invitation links.
bookings:write	Create, change, approve, reject and cancel bookings, move appointments, add notes, and create or revoke invitation links.
customers:write	Create customers and edit their fields.
settings:read	Read the site’s booking settings: currency, timezone, formats and switched-on modules. Never keys or provider details.

Give each key the fewest permissions it needs. A dashboard that only shows upcoming appointments needs read and nothing else.

The person a key acts as is the ceiling. A key that acts as a staff member sees only that staff member’s bookings and never reads customers, whatever permissions it has. Only administrators can create keys that act as an administrator.

Use the Key

Send the key in the Authorization header:

curl -H "Authorization: Bearer cbk_..." \
  "https://example.com/wp-json/core-bookings/v1/admin/bookings?filter=upcoming"

If a proxy or host strips Authorization, send the key as X-Core-Bookings-Key: cbk_... instead.

• Keys work only on core-bookings/v1 routes. They never sign in to wp-admin or other plugins’ APIs.
• A route the key’s permissions don’t cover answers 403. A missing, revoked or expired key answers 401 cb_api_key_invalid.
• Ten failed attempts from one address in ten minutes lock that address out for a while with 429.
• To create an appointment from a server, use POST admin/bookings. It skips spam protection and doesn’t email the customer unless you send "notify": true.

Keep Keys Safe

• Keep keys on servers. Never put one in a web page or a mobile app, where anyone can read it.
• The key list shows each key’s prefix, who it acts as, its permissions, when it expires and when it was last used. A key nobody has used in months is a key to revoke.
• Revoke stops a key immediately. Deleting the user a key acts as revokes it too, and a user who loses their booking role makes the key fail.
• Creating and revoking keys, and every change made with a key, appear in the activity log with the key’s prefix. The key itself is never logged.

OpenAPI Description

Every site serves an OpenAPI 3.1 description of its booking routes at /wp-json/core-bookings/v1/openapi.json. Load it into Postman, Insomnia or a code generator. It lists only the routes of modules you have switched on, and each operation names the permission a key needs in x-core-bookings-scope. It contains no settings or secrets.

JavaScript Client

The plugin includes a small JavaScript client with no dependencies at wp-content/plugins/core-bookings/clients/js/core-bookings.js, with TypeScript types in core-bookings.d.ts beside it. WordPress never loads it. Copy both files into your own Node.js project or front end.

import { CoreBookings } from './core-bookings.js';

const api = new CoreBookings({
  baseUrl: 'https://example.com/wp-json/core-bookings/v1',
  apiKey: process.env.CORE_BOOKINGS_KEY,
});

const { slots } = await api.availability({ service_id: 3, staff_id: 0, date: '2026-12-01' });
const { bookings } = await api.listBookings({ status: 'awaiting_approval', limit: 10 });

Leave out apiKey in a browser: public routes such as availability and the customer’s own booking (with its private token) work without one. Errors come back as CoreBookingsError with an HTTP status and a code such as cb_slot_taken.

API Keys or Application Passwords?

WordPress application passwords also work with the booking API, but they carry everything that user can do anywhere on the site. Use an API key whenever the caller only needs bookings. Use an application password only for tools that also manage other parts of WordPress.