SapanCalDeveloper Docs

Authentication and API keys

How to create, use, rotate and revoke BentoCal API keys.

Every API request is authenticated with an API key that belongs to one application. Send it as a bearer token:

Bash
curl https://api.bentocal.com/au/v1/users/user_123 \
  -H "Authorization: Bearer $BENTOCAL_TEST_KEY"
API keys are server-side secrets. Never put one in a browser, a mobile app or a public repository. Anyone with the key can read and write your users' calendars through your application.

Key format

Keys look like bc_{mode}_{region}_{32 characters}, for example bc_test_au_7Hq2Lm9XvT4kPz8RwN3bYc6JfD1sGa5E.

PartMeaning
bc_Marks a BentoCal key, which helps secret scanners find leaked keys.
test / livetest for keys created while the application is in development, live for keys created in production.
auThe region the application lives in. The key only works on that region's base URL.

The mode is a label for you: it's set when the key is created and doesn't change if you later switch the application's environment. When an application goes to production, create a new key (it starts bc_live_) and revoke the old one.

Create a key

  1. Open your application in the console and go to the API keys tab.
  2. Click Create API key and give it a Name so you can tell keys apart, for example "Production server".
  3. Copy the key from the Save your API key dialog, store it in your secrets manager, tick I've saved this key somewhere safe and click Done.
The Save your API key dialog, showing a new key once with a confirmation checkbox

The full key is only shown once. BentoCal stores a hash of it, plus its prefix and last four characters so you can recognise it in the list. If you lose a key, revoke it and create a new one.

Rotate a key

An application can have several active keys, so you can rotate without downtime:

  1. Create a new key.
  2. Deploy it to your servers.
  3. Check the old key's Last used time on the API keys tab stops moving.
  4. Revoke the old key.

Revoke a key

Click Revoke next to the key on the API keys tab. Requests with it fail with 401 unauthorized straight away. Revoking can't be undone.

Authentication errors

StatusCodeCause
401unauthorizedThe Authorization header is missing or malformed, or the key is unknown or revoked.
400wrong_regionThe key belongs to another region. Use the base URL of the region your application lives in. See Regions and base URLs.
403forbiddenThe application is disabled (Settings → General → Status).
403company_suspendedThe company account is suspended. Contact support.

See Errors for the full list.