# Layerbase agent registration

> Generated from Layerbase source at request time. Follows the auth.md
> agent-registration protocol, plus one Layerbase extension: purchase.

Layerbase runs managed cloud databases. An agent can register, buy a plan
with a payment method it is already authorized to use, and create and use
databases through the Layerbase MCP server, all before any person signs in.
Later, a person can claim the account with Google or GitHub to manage it.

Two paths, pick one:

1. **A person already has a Layerbase account.** Do not register. Connect
   to the MCP server at https://layerbase.com/api/mcp with OAuth sign-in; the person
   approves you in their browser. On the Free plan that gives you the
   database, branch and query tools within their Free limits.
2. **No account, or the person is not available.** Register below and buy
   a plan. There is no free agent account: databases need a paid plan.

## Step 1: Discover

- Protected resource metadata: https://layerbase.com/.well-known/oauth-protected-resource
- Authorization server metadata: https://layerbase.com/.well-known/oauth-authorization-server

## Step 2: Pick a method

Only `anonymous` is supported. External identity assertions (ID-JAG) and
`service_auth` are not accepted.

## Step 3: Register

```http
POST https://layerbase.com/api/agent/register
Content-Type: application/json

{ "type": "anonymous" }
```

The response carries `registration_id`, `identity_assertion`,
`assertion_expires`, `claim_url`, `claim_token`, `claim_token_expires`,
`pre_claim_scopes` (mcp, agent.purchase) and `post_claim_scopes`
(mcp, agent.purchase).

- An UNPAID registration expires 24 hours after it is created.
- A PAID registration never expires for being unclaimed.
- Keep `claim_token`: unlike the base protocol, it stays valid after payment
  until a person claims the account, so you can start the claim days later.

## Step 4: Exchange the assertion

```http
POST https://layerbase.com/api/mcp/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>
```

- Before payment the access token has scope `agent.purchase` and only reaches the purchase endpoint.
- After payment it is an MCP token (scope `mcp`).
- Access tokens last 60 minutes. Exchange again when one expires.
- Every exchange also returns a renewed `identity_assertion` (valid 30 days).
  Keep the newest one. `invalid_grant` means the registration was revoked,
  expired unpaid, or claimed (use the post-claim assertion from the claim).

## Step 5: Purchase (Layerbase extension)

```http
POST https://layerbase.com/api/agent/purchase
Authorization: Bearer <access_token>
Content-Type: application/json

{ "tier": "solo", "contact_email": "person@example.com" }
```

- Plans: Solo $5/month, Pro $15/month, billed monthly from the first
  month. No trial and no introductory discount on agent accounts.
- The response has `checkout_url`. Open it and pay with a payment method you
  are authorized to use. Some cards ask for an interactive check; that may
  need a person.
- Poll `GET https://layerbase.com/api/agent/purchase` with the same token until `status` is
  `paid`. A browser redirect is not proof of payment; this endpoint is.
- Calling POST again returns the same open checkout. If a POST response is
  lost, poll GET; never register again to retry a purchase.
- `contact_email` is where Layerbase may send a reminder about claiming the
  account. It is not verified and never grants access to anything.
- Payments are processed by Polar, the merchant of record.

## Step 6: Use the MCP server

After `status` is `paid`, exchange the assertion again and use the MCP token at https://layerbase.com/api/mcp.
The tools available to an agent account: `whoami`, `list_teams`, `list_engines`, `get_usage`, `list_databases`, `get_database`, `get_connection_string`, `get_database_usage`, `create_database`, `start_database`, `stop_database`, `wake_database`, `delete_database`, `sync_pooler_users`, `run_query`, `list_branches`, `create_branch`, `reset_branch`, `delete_branch`, `change_plan`.
Each one applies the plan limits the dashboard does.

If the plan ends (canceled, refunded, disputed, or unpaid after the retry
period), MCP access stops and the databases are paused after the usual
grace period. Nothing is deleted early; paying again restores them.

## Step 7: Claim ceremony (optional, for a person to take over)

```http
POST https://layerbase.com/api/agent/claim
Content-Type: application/json

{ "claim_token": "clm_...", "email": "person@example.com" }
```

- Only a paid account can be claimed (`payment_required` otherwise).
- The response has `claim_attempt.user_code` and `claim_attempt.verification_uri`.
  Give both to the person: they open the link, sign in with Google or GitHub
  as the email you named, and type the code on that page, not back to you.
- The code is valid for 10 minutes and allows 5 wrong tries;
  POST again for a fresh one.
- Poll `https://layerbase.com/api/mcp/oauth/token` with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<clm_...>`
  every 5 seconds (`authorization_pending`, `slow_down`, `expired_token`).
- On success you get a post-claim access token and identity assertion. Your
  pre-claim tokens stop working and the claim token is spent.
- The account, its databases and its subscription stay where they are. The
  person manages billing and can revoke your access.

## Errors

- `anonymous_not_enabled`: anonymous registration is off. Stop.
- `rate_limited` (429): wait `retry_after_seconds`.
- `invalid_grant`: the assertion is expired, revoked or superseded.
- `invalid_token` (401, purchase): exchange the assertion for a new token.
- `registration_expired` (410): the unpaid registration lapsed. Register again.
- `tier_mismatch` (409): this registration is already buying another plan.
- `payment_required`, `claimed_or_in_flight`, `claim_expired` (claim endpoint).
- `mcp_requires_paid_plan` (MCP): the account has no active paid plan.

## Revocation

- One access token: `POST https://layerbase.com/api/agent/revoke` with `token=<access_token>` (RFC 7009).
- The whole registration: `DELETE https://layerbase.com/api/agent/purchase`. Every token stops
  working; a paid account keeps its databases and subscription for the
  person who claims it, or for support.

Capability document (prices, plans, engines): https://layerbase.com/agents.md