> For the complete documentation index, see [llms.txt](https://docs.osmosworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.osmosworks.com/business-modules/tenants-and-roles.md). # Tenants, roles, and members This module covers tenant workspaces, staff invitations, roles, permissions, and the customer setup flow. ## Tenant lifecycle A tenant is created through the organization onboarding flow. Its lifecycle is expressed with timestamps: * `activatedAt` — workspace created and active. * `suspendedAt` — temporarily blocked. * `removedAt` — permanently removed. Platform administrators can suspend, reactivate, and remove tenants through platform endpoints. ## Tenant profile and settings Each tenant has a profile with sector, estimated staff and customer counts, timezone, locale, default currency, and contact details. Settings include feature flags such as `requireCustomerEmailVerification` and a metadata JSONB map. ## Roles and permissions ### Permission A permission is a granular capability identified by a `code` such as `service.create` or `application:manage`. It has a `resource`, `action`, and `scope` (`PLATFORM` or `TENANT`). ### Role A role groups permissions. Roles can be: * **Platform roles** — no tenant, used for platform administrators. * **Tenant roles** — belong to one tenant and are assigned to staff members. System roles and default templates provide starting permission sets. Custom tenant roles can be created and edited. ### System roles * `SUPER_ADMIN` — the tenant admin role; bypasses all permission checks. * `STAFF_MEMBER` — the default staff role. ## Staff members ### Invitation flow 1. Tenant admin calls `POST /api/v1/tenant/members` with email, name, and role. 2. Backend creates a `TenantMember` and `Principal` and issues an invitation token. 3. An outbox event sends a staff-invite email with an acceptance link. 4. The invitee calls `GET /api/v1/invitations/validate?token=` and `POST /api/v1/invitations/accept` to activate the account and set a password. Invitations expire after `INVITATION_EXPIRY_HOURS` (default 72 hours) and can be resent or revoked. ### Member lifecycle Staff members can be: * **Active** — invitation accepted and not suspended. * **Suspended** — cannot log in or act. * **Removed** — deleted from the tenant. A member cannot suspend or remove themselves (`CANNOT_ACTION_ON_SELF`). ## Customers A customer record belongs to one tenant. Customers may: * Have portal access (linked to a `Principal` with `CUSTOMER` type). * Be org-managed only (no login, reached by view-only links). ### Customer setup link For org-managed customers, staff can send a setup link that lets the customer create portal credentials: * `POST /api/v1/public/customer/setup/resend` sends the link. * `GET /api/v1/public/customer/setup?token=` validates the link. * `POST /api/v1/public/customer/setup` completes account creation. ## Permissions reference | Permission | Description | | ------------------------------------------- | ------------------------------------------------- | | `service.create` | Create services. | | `service.read` | View services. | | `service.update` | Edit and publish services. | | `request:create` | Create customer requests. | | `request:read` | View requests. | | `request:review` | Accept or reject requests. | | `application:read` | View applications. | | `application:manage` | Edit application answers, documents, and parties. | | `invoice.read` / `invoice.manage` | View and manage invoices. | | `payment.read` / `payment.reconcile` | View and reconcile payments. | | `billing.read` / `billing.manage` | View and manage subscriptions. | | `tenant:members:*` | Manage staff members. | | `tenant:roles:*` | Manage roles and permissions. | | `tenant:profile:*` | Read/update tenant profile. | | `tenant:landing-page:*` | Read/update landing page. | | `file:upload` / `file:view` / `file:delete` | File operations. | ## Dashboard The tenant dashboard provides summary metrics for the tenant: * `GET /api/v1/tenant/dashboard/summary` * `GET /api/v1/tenant/dashboard/members` * `GET /api/v1/tenant/dashboard/customers` ## Platform administration Platform users operate outside tenant scope. They can: * Suspend, activate, and remove tenants. * Suspend and activate tenant admins. * Create and update billing plans. * View billing summaries and past-due tenants. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.osmosworks.com/business-modules/tenants-and-roles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.