accept_invitation | Accept a pending invitation and grant the invitee's first role assignment.
Call this when an invitee has a valid invite link and wants to join the
tenant; single-use, consuming the token marks it accepted. |
add_tenant_service | Request a new service subscription for the caller's tenant and return its
status. Call this when a tenant admin wants to add a service (ADR 0016
code fix: requires `admin`, was `customer` realm role only). |
approve_access_request | Approve a pending access request: issue a `member` invitation to the
requester and resolve the request (level `admin` or `owner` of the
request's tenant). The response carries the single-use invitation token
to hand to the requester, who accepts via `accept_invitation`. 409
`access_request.not_pending` unless the request is pending. |
complete_billing | Complete the tenant's billing details: legal-entity name and type, VAT id,
invoice address, invoice email and optional PO reference. Call this when the
owner or a billing contact has the details. EU VAT ids are validated against
VIES by the worker; a failed operation with `billing.vat_check_unavailable`
can be retried by submitting again. Returns `202` with an operation to poll. |
create_access_request | Request access to the tenant that owns the caller's verified email domain. |
create_invitation | Invite an email address to the caller's tenant at the specified access
level and return the invitation, including the raw single-use accept
token. Call this when a tenant admin wants to add a new member; the
invitee accepts via `accept_invitation`. |
create_self_service_tenant | Create a 7-day trial tenant for the caller's business email domain (UC-052).
Needs a verified email on a business domain and `attestation: true`; answers
`auth.email_not_verified`, `tenant.attestation_required`,
`tenant.free_mail_domain` (free-mail address), `tenant.domain_exists`
(a live trial tenant on the domain) or `trial.exists_for_domain` (the
domain already had its one trial; call `start_inquiry`). The trial lasts
exactly 7 days; `ttl` / `expires_at` in the body are ignored. |
dismiss_access_requestdestructive | Dismiss a pending access request (level `admin` or `owner` of the
request's tenant). The requester is mailed — naming the tenant, never the
dismissing admin — and may ask again. 409 `access_request.not_pending`
unless the request is pending. |
enrich_domain | Fetch the caller's domain imprint and suggest legal-entity details (UC-057). |
get_billingread-only | Return the tenant's stored billing details: VAT id, invoice address, invoice
email and PO reference. Call this to check whether billing is complete; only
the owner and billing contacts may read it (`403 rbac.insufficient_level`). |
get_catalog_templatesread-only | Return the enabled ApplicationTemplate catalog, ordered by name. Call this to
discuss trial and template options with a prospect or customer before starting a
trial. If this doesn't answer your question, call `start_inquiry` to ask
4chems directly or request a call. |
get_legal_entity_typesread-only | Return the legal-entity types available for *country*, ordered alphabetically.
If this doesn't answer your question, call `start_inquiry` to ask 4chems directly
or request a call. |
get_my_accessread-only | Return the caller's access level per related tenant. Call this to check
what the current caller is authorized to do before attempting an action
that requires a specific level, or to discover a pending invitation or
access request. |
get_my_operationread-only | Return the status, result and error of an operation the caller started, such as
the `Location` of a `202` from `complete_billing`. Call this to poll it to completion. |
get_onboarding_routeread-only | Return the next onboarding step. If this doesn't answer your question, call
`start_inquiry` to ask 4chems directly or request a call. |
grant_assignment | Grant a role x scope assignment to a tenant member. |
list_consentsread-only | Return the caller's own recorded consents plus the tenant-scope consents of
every tenant where the caller is at least a viewer. Call this to check which legal
documents have already been accepted before asking again. Pass `tenant_id` to
list one tenant's consents only (a caller of several tenants must). |
list_invitationsread-only | List all invitations for the caller's tenant, most recent first. Call this to
show a tenant admin which invitations are pending, accepted, or revoked; the
raw token is never included. |
list_membersread-only | List tenant members with their effective role x scope assignments. |
list_tenant_servicesread-only | Return the caller's tenant's active service subscriptions. Call this before
offering to add a service, to check what is already subscribed. |
record_consent | Record acceptance of a legal document version and return the entry; call this
only after showing the user the document URL and version and receiving an
explicit affirmative answer. |
revoke_assignmentdestructive | Revoke a role x scope assignment from a tenant member. |
revoke_invitationdestructive | Revoke a pending invitation so its token can no longer be accepted. Call this
when a tenant admin wants to withdraw an invite sent by mistake or no longer
needed; accepted invitations cannot be revoked. |
start_account_registration | Start registering a 4chems account with a business email address (`email`,
`name`, optional `company`). Anonymous. Emails a 6-digit code to the address;
no account exists yet. Ask the user for the code, then call
verify_account_registration with the returned challenge_id and code. Free-mail
addresses (gmail.com, ...) are refused: use the company address, or call
start_inquiry. The answer is the same whether or not the address already has
an account. |
start_device_login | Sign in to an existing account by device login (UC-091, RFC 8628). Anonymous,
empty body; the account must exist (start_account_registration, then set the
password through the emailed link). Show `verification_uri` (or
`verification_uri_complete`) and `user_code` to the human, who signs in there,
then call `verify_device_login` with `challenge_id`, waiting `interval` seconds
between calls. The response never contains the Keycloak device_code or the
agent client secret. |
start_inquiry | Store an anonymous inquiry draft and email a 6-digit verification code.
Ask the user for the code, then call verify_inquiry with the returned
challenge_id and code — the inquiry reaches 4chems only after that
verification succeeds. |
start_registration | DEPRECATED: use start_device_login. Deprecated — use start_device_login (same behaviour). |
verify_account_registration | Verify the emailed 6-digit code (`challenge_id`, `code`) and create the
4chems account. Never guess or retry codes, and never ask the user for a
password. |
verify_device_login | Poll a device login to token issuance (UC-091, RFC 8628). Anonymous. While
the human has not signed in yet it answers `{"status": "pending",
"retry_after": <seconds>}`: wait `retry_after` seconds and call again with the
same `challenge_id`. On approval it returns Keycloak's token set
(`access_token`, `refresh_token`, `expires_in`, ...) exactly once; pass the
`access_token` as `authorization` ('Bearer <token>') to every other tool. |
verify_inquiry | Verify the 6-digit code and deliver the inquiry to the helpdesk inbox. |
verify_registration | DEPRECATED: use verify_device_login. Deprecated — use verify_device_login (same behaviour). |
withdraw_access_requestdestructive | Withdraw the caller's own pending access request; no notification is
sent. Any other caller gets 404 `access_request.not_found`, the same as
for an unknown id. 409 `access_request.not_pending` unless pending. |