> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to create and use an API key

Every request to the Billbooks API is authenticated with a Bearer token, an API key you generate from inside your Billbooks account. There's no separate developer portal or self-service signup for this, the key comes from the app you already use.

## Creating a key

1. Sign in to the [Billbooks app](https://app.billbooks.com) as a user of your organization.
2. Go to **Settings > API Keys**. This is available to the account owner by default; for other users, it's gated by a permission your account owner has to explicitly grant.
3. Click **Create API Key** and give it a name.
4. Copy the key **immediately**. It's shown exactly once. Billbooks only stores a hashed version, so if you lose it, you'll need to revoke it and create a new one.

Keys look like `bb_live_` followed by 40 random characters, `bb_live_a1b2c3...` (48 characters total). There's no separate sandbox or test-mode key format, every key is a live key.

Your organization can hold up to 50 active keys at once, useful if you want a separate key per integration so you can revoke one without affecting the others.

## Using a key

Pass it as a Bearer token on every request:

```bash theme={null}
curl https://app.billbooks.com/api/public-api/v1/clients \
  -H "Authorization: Bearer bb_live_your_key_here"
```

<Warning>
  A missing, malformed, unknown, revoked, or expired key all return the exact same generic 401 response, on purpose. The API deliberately doesn't tell you which failure mode applies, so a caller can't use the error message to probe for valid keys.
</Warning>

## Key lifetime

Keys don't expire on their own. There's currently no way to create a key with a built-in expiration date, every key is valid until you manually revoke it. If your security posture needs expiring credentials, build that into your own rotation process rather than relying on the API to enforce it.

## Rotating or revoking a key

There's no rotation endpoint, rotating a key means creating a new one and revoking the old one from **Settings > API Keys** in the app. Revoking is immediate: a revoked key stops working right away and can't be un-revoked.