Authentication

One personal API key per thing you connect, sent as a bearer token.

In shortCreate a key under Settings → Integrations in the app, then send it as Authorization: Bearer bbk_…. The key is shown once; if you lose it, revoke it and make another.

Creating a key#

Sign in and go to Settings.
Choose API keys and webhooks.
Give the key a name — the tool you are connecting, such as "Zapier". Only you see it, and it is how you will recognise the key later.
Choose what it may do (below).
Select Create key, and copy it straight away.

The key is displayed once and never again. That is deliberate: we store only a hash of it, so we could not show it to you later even if you asked. If you lose one, revoke it and create another — there is no recovery, and a key you cannot account for should not stay alive.

What a key may do#

Two choices, not a grid of checkboxes.

Choice	Scopes	Can	Cannot
Read only	`event_types:read` `bookings:read`	List event types, list and read bookings, check availability.	Create or cancel anything. Manage webhooks.
Read and write	the two above, plus `bookings:write` `webhooks:manage`	Everything: create bookings, cancel them, mint invite links, subscribe to webhooks.	Edit event types, availability or your profile. Those are not in v1 at all.

Choose read-only unless the tool genuinely needs to book. A reporting dashboard with a read-only key cannot cancel a customer's appointment, however wrong its code is.

A call that needs a scope the key lacks returns 403 and names it:

{"error":{"code":"insufficient_scope","message":"this token is missing the bookings:write scope"}}

The scope is checked before the body is validated, so this is the first thing you hear about — you will not spend an afternoon fixing a payload for a key that was never going to work.

Sending the key#

curl https://api.marubox.jp/v1/me \
  -H "Authorization: Bearer bbk_your_key_here"

GET /me is the call to use for testing a connection: it works with any valid key whatever its scopes, and it returns the scopes the key carries, so a connector can label the connection and warn about what it will not be able to do.

Looking after keys#

One key per integration. Then switching one off does not break the others, and "last used" tells you which is which.
Never in a browser, a mobile app, or a public repository. A key carries your whole account's permissions; anyone holding it is you. Server-side only.
Revoke rather than rotate quietly. Revocation takes effect on the next request.
Ten keys maximum per account, which is well past the point where a list stops being useful.

Keys do not expire. They stop working when you revoke them, or when the account is deleted.

OAuth, later#

API keys are right when you are connecting your own account to something. They are wrong for an app that serves other people's Business Box accounts: you would be asking strangers to paste a credential that can cancel their bookings.

For that, OAuth 2.1 with PKCE is coming, along with a remote MCP endpoint. Every 401 from this API already carries the discovery pointer it will use:

WWW-Authenticate: Bearer resource_metadata="https://api.marubox.jp/.well-known/oauth-protected-resource"

That endpoint is not live yet. The changelog is where it will be announced.

Common questions

I lost my API key. Can you show it to me again?

No — only a hash of it is stored, so nobody can recover it, including us. Revoke that key and create a new one.

Can an API key be limited to one event type?

Not in v1. Scopes are read-only or read-write across the account. If you need narrower access, say what for — it is the kind of thing that gets built when somebody asks.

Does a revoked key stop working immediately?

Yes, on the very next request. There is no cache and no grace period.

Can I use a session cookie instead of a key?

No. The API ignores cookies entirely, by construction — the routes live outside the part of the app that reads them. That is what stops a logged-in browser being driven into calling the API from another site.

Last reviewed 28 September 2026.