#Provisioning

Once your tenant has its first admin, everything else is self-service under the /access/* surface: add users, mint API tokens, assign roles, author policies, and bind a least-privilege policy to a token for cross-tenant access. (Provisioning a brand-new tenant and its first admin is a one-time platform-operator step done during onboarding.)

Authenticate as a tenant admin with a Personal Access Token (HTTP Basic auth) — enter it once in the Authorize bar at the top of this page and every Try it below uses it. Each example body is pre-filled; the console targets staging by default. Full request/response schemas are in the linked API reference.

#Roles, policies, grants — the vocabulary

• A role is a per-tenant system policy (tenant_admin, entity_editor, workflow_admin, viewer, app_user, …). Every new tenant is auto-seeded with the full catalogue. List them at GET /access/roles; the ids are what you pass as role_ids / role_id.
• A policy is a named bundle of grants you author for least-privilege scoping (e.g. read-only access to a few shared resources).
• A grant authorizes a principal (user, team, or policy) to act on a resource. Grants and cross-tenant shares are covered in Shares & Grants.

#Add a user

Create a user in your tenant and assign their initial roles in one call. The call is idempotent on email — an address that already exists in the platform reuses its account and just adds a profile in your tenant.

role_ids takes role ids from GET /access/roles. DELETE /access/users/{authUserId} soft-deactivates the profile in your tenant; the underlying account stays intact.

#Mint an API token

Tokens belong to a (user, tenant) pair. A fresh token runs in standard mode — it acts with the target user's full effective permissions in the tenant.

The response carries client_id and client_secret (helm_tk_…) — the secret is returned once. Use the pair as HTTP Basic credentials (base64(client_id:client_secret)). Pass policy_id here to mint a scoped token in one step, or attach one later (below).

#Assign a role to an existing user

Roles can be assigned after the fact too:

#Scope a token with a policy (least privilege)

For a least-privilege token — especially one a partner tenant uses to read only the resources you shared — author a policy, give it grants, then bind it to the token. First the policy shell:

Add its grants (see Shares & Grants for the grant shape and the cross-tenant read-only rule), then bind the policy to a token — this flips the token into policy-mode, acting as exactly that policy:

The bound policy must be a tenant-local policy you authored — not a manifest, and not a policy derived from an app spec or workflow (those are rejected). DELETE on the same path clears the binding (back to standard mode). A change applies on the token's next use.

Standard mode vs policy mode. A standard-mode token is the union of the user's role/policy assignments. A policy-mode token acts as one policy — narrower, predictable, and the right choice for cross-tenant or integration tokens. The same user yields different access under different bound policies.

#Cross-tenant access

To let another tenant read your data, you need both a tier-1 share (you → them) and a tier-2 grant (their policy → the resource). The mechanics, the read-only guardrail, and worked examples are in Shares & Grants.

#Secrets

Tenant secrets (and the scoped references apps/workflows wire into their config) are managed at /access/secrets. See Secrets.

#API reference

Every user, token, role, policy, grant, share, and secret operation — with full schemas and an interactive console — is in the API reference.