# BounceLayer auth.md

> How an AI agent gets and uses a BounceLayer API key. BounceLayer uses API
> keys sent in the `X-API-Key` header. There is no OAuth.

## Option A: a person signs up

Sign up at https://bouncelayer.com/sign-up (300 free checks every month), then
create a key at https://bouncelayer.com/dashboard/api-keys.

## Option B: the agent signs itself up

Over HTTP:

`POST https://api.bouncelayer.com/api/auth/agent/register`

```json
{"type": "anonymous", "label": "my-agent (optional)"}
```

Over MCP: call the keyless `create_agent_account` tool on https://api.bouncelayer.com/mcp/.

Either way you get back (the `api_key` and claim link are shown **once**;
store them safely and never put them in logs, URLs or chat messages):

```json
{
  "api_key": "bl_live_...",
  "credits_granted": 25,
  "claim_url": "https://bouncelayer.com/agent/claim?token=clm_...",
  "claim_token": "clm_...",
  "claim_token_expires_at": "<ISO 8601>"
}
```

The key works straight away with 25 free credits. Sign-up is
limited per network and site-wide; a `429` says when to try again.

## Hand the account to a person

Give `claim_url` to the person you work for. When they open it and set an
email and password, the account becomes theirs and is topped up to
300 free checks a month. The page calls
`POST https://api.bouncelayer.com/api/auth/agent/claim` with
`{"claim_token": "clm_...", "email": "owner@example.com", "password": "<8+ chars>"}`.
The API key keeps working.

## Use the key

```http
X-API-Key: bl_live_...
```

- REST API: https://api.bouncelayer.com/api/v1 (start with `POST https://api.bouncelayer.com/api/v1/verify/single`)
- MCP server (Streamable HTTP): https://api.bouncelayer.com/mcp/

## Errors

- `401`: missing or invalid `X-API-Key`.
- `402`: out of credits. Claim the account or buy credits.
- `429`: rate limited; wait for the `Retry-After` header.

## Revoke a key

The account owner deletes keys at https://bouncelayer.com/dashboard/api-keys
(or `DELETE /api/auth/api-keys/{key_id}`).