API keys

An API key lets software access a business without an interactive sign-in.

Getting one

An owner, admin or technical user can create a key in Connections, under the account menu. Choose the permissions it needs and an expiry date.

Copy the key when it is created: Bottle shows it only once and stores a fingerprint, not a recoverable copy. If you lose it, revoke it and create a replacement.

Keys start with btl_, which helps secret scanners identify accidental leaks. Store keys securely and keep them out of source control.

Using one

Send the key as a bearer token:

curl https://api.bottle.example/customers \
  -H "Authorization: Bearer btl_7f3a9c21_..."

Replace the example host with your Bottle API address. The key identifies its business. X-Tenant-Id is optional; if supplied, it must match that business.

What a key cannot do

Owners and admins delegate permissions within their own access. Technical users have an explicit exception: they can grant operational data permissions for integrations without having those screens available in their app. They cannot use a key to grant people management, change general business settings or manage keys. Connected assistants do not receive this exception.

Managing keys and changing business owners require a signed-in person.

Request activity

Use View activity in Connections, or GET /api-keys/activity with a signed-in owner, admin or technical session. API keys cannot read or change the activity log. Query parameters include keyId, outcome=errors, limit (up to 100) and the returned next value as before for the next page.

The log covers requests reaching a permission-protected route with a valid key, including permission refusals, wrong-business requests and rate limits. Invalid, expired or revoked keys cannot be reliably associated with a business and do not create an entry.

Entries include method, route template (not customer IDs or query values), required scope, status, duration and available IP address. Request and response sizes come from reported Content-Length headers and may be unavailable. Bodies, response contents and secrets are never stored. Entries are available for 30 days, including after key revocation, and the daily job deletes expired entries in small batches.

Expiry and revocation

Choose a one-year expiry, a specific date or no expiry. A one-year expiry provides a regular opportunity to review access.

Business managers receive expiry reminders 30, 15, 7 and 1 days before expiry, and another when the key expires. Revocation takes effect on the next request.