API keys

A key lets a program act on one business without a person present.

Getting one

An owner or admin creates it under Connections. They choose what it may do and when it expires. The key is shown once, at creation; only a fingerprint is stored, so a lost key is replaced rather than recovered.

Keys look like btl_7f3a9c21_.... The btl_ is deliberate: secret scanners key off known prefixes, so a key pasted into a public repository can be spotted.

Using one

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

The key names its own business, so X-Tenant-Id is optional. Send it if you like, and it must match, which catches a key pointed at the wrong place.

What a key cannot do

A key never has more than the person who created it. Managing keys, and changing owners, need a person signed in.

Expiry and revocation

A key can run for a year, until a date you pick, or forever. We recommend a year. Everyone who can manage the business is emailed 30, 15, 7 and 1 days before it expires, and again when it does.

Revoking takes effect on the next request.