# LakehouseBox: how an agent gets access

You are an agent. LakehouseBox (Apache Iceberg catalogs operated in Germany) gives you a credential in one of two ways.
Never ask a person for a key, and never show one in the conversation: the CLI saves it to
`~/.config/lhbox/credentials.json` and reads it from there.

## 1. A person is at hand: they approve this machine

```sh
curl -fsSL https://lakehousebox.com/install.sh | sh
lhbox login            # prints a link and a code; the person signs up or logs in, types the code and approves
```

The API underneath is the OAuth device authorization grant (RFC 8628) in this API's error envelope:
`POST https://api.lakehousebox.com/v1/auth/device`, then poll `POST https://api.lakehousebox.com/v1/auth/device/token`.

## 2. No account and no person yet: register without one, a person claims it later

This is what auth.md calls anonymous registration.

```sh
lhbox new              # or: curl -X POST https://api.lakehousebox.com/v1/agent/identity   (no body, no key)
lhbox duckdb           # write tables now
lhbox claim            # later: a link and a code for the person; `lhbox claim --resume --wait` saves the new key
```

- `POST /v1/agent/identity` answers `api_key` (once), `registration_id`, `organization` (status `unclaimed`),
  `catalog`, `expires_at`, `limits`, `pre_claim_scopes` (`catalogs:read`, `catalogs:write`), `post_claim_scopes`,
  `terms`, `how_to_use`, `next`. Sending it accepts the Terms of Service (https://lakehousebox.com/legal/terms/, clause
  2.5) and the Acceptable Use Policy for whoever runs you. `{"type": "service_auth"}` and
  `{"type": "identity_assertion"}` answer `service_auth_not_enabled` and `issuer_not_enabled`: only `anonymous` is
  offered.
- Before the claim: 1 GB, one catalog, nothing public, data writes only (`403 claim_required` for anything else),
  deleted with its data at `expires_at` (72 hours), at most 5 an hour and 20 a day per network address.
- The claim: `POST /v1/agent/identity/claim` with the key as the bearer answers `user_code`,
  `verification_uri_complete`, `device_code`, `interval`, `expires_in` (a day at most). The person opens the link,
  signs up or logs in, types the code you give them, and chooses the organisation that keeps the catalog. Poll
  `POST /v1/auth/device/token {"device_code": …}`: `authorization_pending`, then a new `api_key`. Every credential from
  before the claim stops working at that moment.

The wire format of the auth.md protocol itself (a service-signed `identity_assertion` exchanged with the JWT-bearer
grant, and the claim grant at a token endpoint) is not implemented; the routes above are the contract.

More: https://lakehousebox.com/new · https://lakehousebox.com/docs/agent-setup/ · https://lakehousebox.com/llms.txt