For agents · the instructions your agent follows. The page for people: Words you'll see · Work with your team

Access and permissions

This page says who can do what in an organisation, and how to give, check and take away access. Access is decided at two levels: a role in the organisation, and a grant on each catalog.

The short path

lhbox whoami                                              # who you are, your level on each catalog
lhbox catalog grants sales                                # who holds what on a catalog, and how
lhbox catalog grant sales --principal <id> --level read   # give read on one catalog
lhbox catalog revoke sales --principal <id>               # take it away; their key pair rotates
lhbox catalog update sales --access organisation          # or let every member of the organisation read it
lhbox org policy                                          # what members may do, and whom to ask
lhbox audit --since 7d                                    # who did what this week

lhbox org members and lhbox token list show the principal ids.

Who can hold access

Everything belongs to an organisation. An organisation holds catalogs, a catalog holds namespaces, and a namespace holds tables. A role says what you may do to the organisation, its people and its tokens. A grant says what you may do to one catalog's data, and covers every namespace and table in it; with Enterprise, a grant can also cover one namespace or one table. The API calls a catalog a warehouse (/v1/warehouses, warehouse_id).

People log in on the account page with email and password, or with Google. Each holds one of two roles, admin or member. The person who creates the organisation is its first admin.

A person can add two protections to their own login, both under Settings on the account page. A passkey signs you in with the device's fingerprint, face or PIN, with no address and no password (up to 20 per account). Two-factor authentication asks for a 6-digit code from an authenticator app after the password; setting it up gives eight single-use backup codes, shown once. A passkey also answers that second step. Neither changes what a key or a token may do.

Tokens are the organisation's machine identities: an agent, a script, a scheduled job. A token has its own API key, an organisation role (member by default) and its own catalog grants. A token never holds more than the person or token that created it. Its role and grants are capped by the creator's, at creation and at every edit.

Organisation roles

capability admin member
see the organisation, its members, tokens and usage yes yes
see a catalog: its name, size and access list every catalog the catalogs they hold something on
invite and remove members, change roles, claim domains, rename the organisation yes no
read and write catalogs write on every catalog the catalogs they created or were granted, and read on those open to the organisation
create a catalog yes yes, and gets write on it
change a catalog's general access yes no
rotate a catalog's credentials, delete or restore it yes no
publish or unpublish a catalog yes, unless publishing is set to nobody (unpublishing always) no, unless publishing is open to members (then on catalogs they can write)
grant or revoke read and write on every catalog only where they hold write, never above their own level, and only grants they made
create tokens, approve lhbox login and MCP clients, create API keys yes yes by default (member tokens, grants up to their own); an admin can turn this off
create hosted agents yes yes by default; an admin can turn this off
revoke tokens any the ones they created
read the audit log the organisation's events their own events

A token's role works exactly like a person's, with one difference. A human admin holds write on every catalog by role. An admin token holds only its grants: it sees every catalog and may grant itself what it needs.

The last human admin cannot leave, be removed or be demoted. Tokens do not count as admins for this.

lhbox org list                                    # your organisations: name, id, your role
lhbox org members                                 # its people and their roles
lhbox org invite --email ana@example.com --catalog sales --catalog ops:write   # a member, with two catalogs
lhbox org role --principal <id> --role admin      # an organisation keeps at least one admin
lhbox org domain --domain example.com             # prints the DNS TXT record to publish
lhbox org domain --domain example.com --verify    # once the record is published
lhbox org set --domain-join on                    # offer membership to people on the verified domain
lhbox org offers && lhbox org join --org <handle> # a person on that domain: see the offer, accept it

Joining an organisation, a page of its own: Invitations, claiming your company's email domain, and joining an organisation by domain: who may, how long each step lasts, what is remembered.

What members may do

An admin decides four things for the whole organisation. They are on the account page under Settings › General › Member permissions, or in lhbox org policy. Everyone in the organisation can read them. Only an admin who is a person changes them; a token cannot, whatever its role.

The API checks each one whenever the thing is made, whatever made the request: the account page, the CLI, an MCP client or a script.

setting who may default
publish_catalogs admins; members (admins, and member people on a catalog they can write; a member token never publishes); or nobody (admins included) admins
connect_agents members (admins and members) or admins: tokens (lhbox token create), lhbox login approvals, MCP clients approved on the consent page, and personal API keys members
hosted_agents members or admins: who may create hosted agents members
new_catalogs not a permission but a default: the general access a new catalog starts with, restricted or organisation restricted

A token counts as what its organisation role says: a member token is a member here.

A personal API key acts as you in every organisation you belong to. So it is refused while any of them lets only its admins connect agents and you are a member there. lhbox login --issuer exchanges your identity provider's sign-in for such a key, and is refused alike.

Changing a setting never undoes what exists:

  • Public catalogs stay public when publishing is narrowed or turned off. The settings page lists them with a Make private button.
  • An admin can always make a catalog private, or narrow it (stop publishing its files).
  • Tokens, connections and hosted agents made before keep working until someone revokes or deletes them.
  • Catalogs that exist keep their general access when new_catalogs changes.

A refused request answers 403 org_policy_forbids. It carries the setting (policy), its value, and a remedy naming the organisation's admins to ask. Every change is recorded in the audit log as org.policy_update, with each setting's value before and after.

lhbox org policy                                          # the settings, what you may do, whom to ask
lhbox org policy --connect-agents admins                  # admin: only admins connect agents from now on
lhbox org policy --publish-catalogs nobody                # admin: nobody publishes; public catalogs stay public
lhbox org policy --new-catalogs organisation              # admin: new catalogs start open to every member

Catalog grants: read and write

Each person or token holds read, write or nothing on each catalog:

  • A member reads no catalog until given access. They hold what they are granted and what they created.
  • On a catalog open to the whole organisation, every member holds read (see General access).
  • Whoever creates a catalog holds write on it.
  • A human admin holds write on every catalog.
  • A token holds exactly the grants it was given. With none, it can reach no catalog.
  • A hosted agent is granted a catalog only by its creator or an admin. Anyone else, even with write on that catalog, gets 403 not_agent_manager.
level lets you
read list and query tables, get the catalog's read-only connection recipe, browse and preview the catalog's files, list its uploaders and sinks
write all of read, plus create, change and drop tables, commit data, create uploaders and sinks, set lifecycle rules and the catalog's default format version

The catalog and its storage enforce the limit, not only the API: a read credential is refused on every write.

lhbox catalog list                                # every catalog you can see, with your level on each
lhbox catalog grants sales                        # who holds what, and how (admin, membership, creator, explicit)
lhbox catalog grant sales --principal <id> --level read
lhbox catalog revoke sales --principal <id>

A catalog cannot be shared with another organisation. To let someone outside read it, send them the read-only recipe (lhbox connect --readonly --show-secrets). Or have an admin make it public (lhbox catalog publish).

General access

Every catalog has one setting for the members of its organisation:

setting in the API who reads the catalog
Restricted org_access: none admins, its creator, and the people and tokens granted it
Everyone in the organisation org_access: read the same, plus every member, and anyone who joins later

A new catalog is Restricted. Its creator can open it when creating it. An admin can make open the default for new catalogs with new_catalogs (see What members may do). An MCP connection cannot ask for an open catalog: it creates a Restricted one, and a person opens it.

lhbox catalog create sales --access organisation       # open from the start
lhbox catalog update sales --access organisation       # admin: every member reads it from now on
lhbox catalog update sales --access restricted --yes   # admin: only the people and tokens granted it
lhbox catalog get sales                                # the setting, and your level

On a catalog that exists, only an admin of the organisation changes it: a person, or a token with the admin role. On the account page it is in the catalog's Access section.

A member reading an open catalog is listed with via: membership. Write still takes a grant.

Opening a catalog gives every member read on it. It is refused with 409 scoped_grants_held while a member who would start reading holds a namespace grant there. The answer names them: revoke those grants, then open it.

Making a catalog Restricted takes it from the members who read it only as members. It also reaches what they made and fetched:

  • Tokens they created are capped to what their creator still holds. Hosted agents of theirs that read it are paused.
  • If one of them fetched the catalog's read-only key pair, that pair is replaced. A recipe pasted into an engine stops working: run lhbox connect for a fresh one.

Admins, the creator, and people and tokens with a grant of their own keep their access. At a terminal the CLI says how many members lose the catalog and asks; anywhere else, pass --yes. GET /v1/catalogs/{id}/org-access returns those counts before you change anything.

A member without access does not see the catalog. It is not in lhbox catalog list or on the account page. Every request that names it gets 404 warehouse_not_found, the answer a name nobody used gets: nothing says whether the catalog exists. The same goes for a member whose read an admin revoked on an open catalog.

What else names a catalog follows the same rule for that member. A token's or a service account's grants on it are counted (grants_hidden), not named. An agent that reads it is not listed. Creating a catalog with its name answers 409 already_exists, which says the name is taken and nothing more.

A member who holds only a namespace or a table of a catalog still sees the catalog, with level none and what they hold in it.

Each change is recorded in the audit log as warehouse.org_access, with the value before and after and the number of members it reached.

Tokens for agents

lhbox login: sign a machine in as you

lhbox login                 # opens your browser; you click Allow
lhbox login --no-browser    # the browser is on another computer: a link and a code instead
lhbox login --no-wait       # with a code: print the link and exit; finish later with --resume

A login is yes or no. The key it saves acts as you: it can do what you can do on the website, in every organisation you belong to, for 30 days. Then run lhbox login again. You see and revoke it under Settings › Access keys.

On a computer with a browser, lhbox login opens the account page. You sign in if needed and click Allow; the browser comes back to this computer and the CLI is signed in. An agent running on this computer can give you the link instead: it works when you open it on this computer.

Without a browser here (an SSH session, a server), or with --no-browser, the CLI prints a link and a code. Open the link anywhere: the code is filled in, and the page says what asks (its name, machine, where and when it started). Approve only a login you or your agent started, and deny one someone else sent you. The code is valid for 15 minutes (an hour with --no-wait).

The CLI saves the key to ~/.config/lhbox/credentials.json and never prints it, unless you pass --show-key.

A key limited to some catalogs (for a program, a server, or someone else's agent) is not made by lhbox login. Make it on the website (Settings › Access keys) or with lhbox token create below, and give it to the program as LHBOX_API_KEY.

Several accounts on one machine: profiles

Each login is saved under a profile. Without one, it is the profile default. To keep a second account or organisation beside the first, log in under another name:

lhbox login                       # profile default
lhbox --profile acme login        # a second account, kept beside the first
lhbox profile list                # every profile on this machine, the one in force marked
lhbox profile use acme            # make acme the profile every command uses
lhbox --profile default whoami    # one command as another profile, without switching

The profile in force is the first of: --profile <name> on the command, the LHBOX_PROFILE environment variable, the one lhbox profile use chose, then default. lhbox login says which profile it saved to, and lhbox whoami names the profile its key came from when it is not default.

lhbox login --new replaces the key of the profile in force. It does not add a second account. Use it to swap the machine's key for a new one; use --profile to keep two. Before the approval, it says when it is about to replace a key that still works.

To remove one: lhbox logout --profile acme revokes its key and forgets it; lhbox profile delete acme --yes only forgets it on this machine (the key stays valid until revoked on the account page).

Every profile lives in the one file ~/.config/lhbox/credentials.json, readable only by you. Two other ways to keep accounts apart, mostly for scripts and CI: LHBOX_CREDENTIALS=<file> points the CLI at another credentials file, and LHBOX_API_KEY (or --api-key) uses a key for that process alone and ignores saved logins.

Which file every command reads and writes is the first of: LHBOX_CREDENTIALS (a relative path is taken from the directory you ran the command in), $XDG_CONFIG_HOME/lhbox/credentials.json when XDG_CONFIG_HOME is set to an absolute path, then ~/.config/lhbox/credentials.json. If you set XDG_CONFIG_HOME after logging in, run lhbox login again, or set LHBOX_CREDENTIALS=~/.config/lhbox/credentials.json to keep using the earlier login.

lhbox token create: a token by hand

Use it for a program, a server, or an agent that should not act as you: it holds only the catalogs you grant it. The API key is shown once. Give it to the program as LHBOX_API_KEY.

lhbox token create --name nightly-load --grant sales:write --grant raw:read
lhbox token update nightly-load --grant sales:read   # the list replaces the current grants
lhbox token update nightly-load --role admin         # capped by your own role
lhbox token list
lhbox token revoke nightly-load

A token can create tokens within its own role and grants. Revoking a token also revokes every token below it.

The MCP server

Approving the remote MCP server also creates a token. It holds its own grants, or all catalogs, including ones created later, at read or at read and write. With all catalogs, it holds that level on each catalog, but never more than you hold there yourself at the moment it is used. So a catalog you create later needs no new approval, and one you lose is gone from it at once. The account page lists it as "All catalogs (read)". Connecting again changes it; revoking ends it.

That token reads and writes data only. Whatever you approve, it cannot:

  • create keys or tokens, or grant catalogs;
  • invite, change or remove members;
  • publish or delete a catalog;
  • change your account.

Those stay with you, and the token gets 403 mcp_human_only. Nor does it get the catalog's key pair: only storage credentials that expire within about an hour. A public catalog's shared reader key, public by design, is the one exception.

Engine credentials, a page of its own: What an engine holds for a catalog: the key pair, catalog tokens, per-table storage credentials and how long each lives, and the special-purpose credentials.

Revoking and rotating

to stop do this takes effect
a machine or agent lhbox token revoke <name>, or the account page at once, for the token and every token it created; key pairs they were handed are rotated
a person's or token's access to one catalog lhbox catalog revoke <catalog> --principal <id> at once; a key pair they were handed is rotated within seconds
a person an admin removes them from the organisation at once; their grants and tokens go too, and the key pairs they or their tokens were handed are rotated
every member's read on an open catalog lhbox catalog update <catalog> --access restricted --yes (admin) at once; the read-only key pair is rotated within seconds if one of them fetched it
an uploader lhbox catalog uploader revoke <catalog> --uploader <name> at once
a sink's send key lhbox sink delete <sink> at once
every copy of a catalog's key pair lhbox catalog rotate <catalog> (admin) old keys, catalog tokens made from them and storage credentials issued from them, at once

Removing access rotates the pairs the person or token was handed. The answer lists them under keys_rotated.

Rotate by hand whenever a recipe may have leaked to someone outside. A manual rotation replaces both pairs and can take a minute. Every engine then needs a fresh recipe (lhbox connect again).

Deleting a catalog

Only an admin can delete a catalog, and the name must be typed out:

lhbox catalog delete sales --confirm sales
lhbox catalog restore sales                       # within the grace period

A deleted catalog stays restorable for a 7-day grace period. From the moment it is deleted, it is gone for everyone:

  • it leaves every list, and its routes answer that it was deleted;
  • its sinks are refused;
  • within seconds, its key pairs and catalog tokens stop working and its uploaders are revoked;
  • storage credentials already issued run to their own expiry, about an hour.

During the grace period, the name stays reserved. The catalog no longer counts towards the number of catalogs you may have, but its bytes still count towards your storage.

lhbox catalog restore brings back the same catalog: its id, name, tables, files, settings and grants. It comes back private and without its uploaders. It also comes back with a new key pair, since the old one was revoked: run lhbox connect again.

When the grace period ends, tables, files and credentials are deleted for good and the name is free. The purge runs within a few hours. --purge skips or ends the grace period; nothing brings the catalog back after a purge.

The audit log

Grants, tokens, invitations, role changes, credential vending, rotations and deletions are recorded. Secrets are never written to it. A member sees their own events; an admin sees the whole organisation's with --org.

lhbox audit --since 7d
lhbox audit --org <org> --action 'token.*' --limit 200

When it fails

what you see what it means what to do
403 org_policy_forbids the organisation's member permissions keep this to admins ask one of the admins its remedy names
403 mcp_human_only an MCP connection asked for an account action do it yourself, with the CLI or the account page
404 warehouse_not_found for a catalog a colleague named no catalog has that name, or it was not shared with you check the name, then ask an admin of the organisation for access
403 forbidden with level: none you hold a namespace or a table of this catalog, not the catalog ask one of the people its can_grant names
409 scoped_grants_held opening the catalog would end the namespace grants it names revoke them, then open it; or keep it Restricted
confirmation_required from catalog update --access restricted members would lose the catalog, and no terminal to ask read the count in the answer, then pass --yes
a write refused with a read credential you hold read on this catalog ask someone with write to grant it
a recipe that stopped working its key pair was rotated fetch a fresh one: lhbox connect, or the account page
the last admin cannot leave or be demoted an organisation keeps one human admin make another person admin first
a domain claim refused public mail domains cannot be claimed claim your own domain

Every command is in the CLI reference; the routes are in the API reference.

Numbers and dates

what figure
invitation valid 7 days; at most 20 catalogs
lhbox login code valid 15 minutes (an hour with --no-wait)
catalog token, storage credentials about an hour
rotation after access is taken away within seconds
manual lhbox catalog rotate can take a minute
verified domain looked up once a day; three definite misses in a row, or a week without any answer, unverify it
a departure, for domain join remembered 12 months, then forgotten
departures before 2026-10-01 taken from the audit log; someone whose account was deleted before then left no address to match
deleted catalog restorable 7 days; the purge runs within a few hours after
audit log events kept 400 days