Concepts and terminology
These are the terms used across the Identity Management screens, the API tokens UI, and the SSO flow. Skim this page once before configuring SSO or issuing API tokens — most surprises come from confusing role with permission, or organization with tenant.
Organization
The top-level account. Everything in Praxis — tenants, users, invitations, API tokens, SSO connections — lives under exactly one organization. You may belong to more than one organization; the org/tenant switcher in the shell controls which one is active.
- An organization has a name and an owner (the user who created it).
- Org-wide settings (members, invitations, SSO connections, default tenant) are managed under Organization at
/identity/settings.
Tenant
A partition inside an organization used to scope data and access. Most product data — pipelines, collectors, alerts, metrics, knowledge — is tenant-scoped. A tenant typically maps to a team, environment, or customer of yours.
- Tenants are listed and created from the Tenants tab of Organization, and configured per tenant under Tenants (
Tenant settings). - The org/tenant switcher determines the current tenant. APIs and screens read it from your session.
- Tenant names must be unique within the organization.
User and identity
A user is a person (or service identity, where supported) that can sign in. Each user has:
- An email address (the primary identifier across SSO and password sign-in).
- An optional profile (first name, last name) maintained on the Profile page (
/identity/profile, opened from the avatar menu). - One or more memberships — links into organizations and tenants, each carrying a role.
A user can belong to several organizations and several tenants. The active membership at any moment is determined by the current organization and tenant in the switcher.
Role
A named bundle of capabilities assigned at the org or tenant level. Praxis ships four roles:
| Role | Typical use |
|---|---|
| owner | Full control of the org/tenant, including high-risk settings and ownership transfer. |
| admin | Manage users, invitations, SSO connections, and most settings. |
| member | Day-to-day product work with read/write on assigned resources. |
| viewer | Read-only access to permitted resources. |
Roles are assigned when a user is invited (Invitations) or provisioned by SSO (see SSO role mapping and IdP setup guides). They can be changed later from the Users screens.
Permission and scope
A permission is a single capability string of the form <resource>:<action>, for example pipeline:read or organization:write. The product uses two permission catalogs:
idm— identity-service capabilities (organizations, tenants, users, invitations, SSO).praxis— pipeline-platform capabilities (pipelines, collectors, alerts, metrics, knowledge).
In the UI, roles are the user-facing concept — you usually do not pick individual permissions. Where you do see them is when you create an API token: the token's scopes are explicit permission strings such as pipeline:read, collector:read, metrics:read, or organization:read.
A token's scopes are an intersection with what the issuing user is allowed to do — you cannot mint a token more powerful than the user creating it.
Org/tenant context
Most APIs and screens require two pieces of context in addition to the caller's identity:
| Context | Carried as | Set by |
|---|---|---|
| Organization | session + x-ne-org-id (where applicable) | Org/tenant switcher in the shell |
| Tenant | session + x-ne-tenant-id (where applicable) | Org/tenant switcher; deep-link query string ?tenant=…&orgId=… |
When you change either control in the shell, the URL and in-app context update together. If you deep-link into Tenants settings with a tenant and orgId query string and the IDs are valid, the page opens directly there.
Collector M2M clients (org + tenant binding)
Praxis collectors authenticate to the platform with an OAuth2 machine-to-machine (M2M) client — the --key / --secret (or KEY= / SECRETKEY= on Windows) you pass to the collector installer. These clients are minted by identity-service via CreateCollectorM2MClient and are bound at creation time to a specific organization and tenant.
- The installer passes the org ID and tenant ID alongside the M2M credentials (
--org/--tenantflags on Linux, macOS, and Kubernetes;ORG=/TENANT=properties for the Windows MSI). The values shown by Praxis when you enroll a collector already match the binding of the M2M client it issues. - On every authenticated call, identity-service compares the org/tenant on the token introspection result against the
x-ne-org-id/x-ne-tenant-idrequest headers. Mismatches return 403 Forbidden — a collector cannot connect to a different org or tenant than the one its M2M client was issued for. - M2M clients can confirm their own binding by calling
GET /v1/auth/m2m/self, which returns the org and tenant the client is bound to without requiring any extra context headers.
Authentication method
How a session gets created. The product supports:
- Password sign-in (email + password), with optional email verification and account recovery flows.
- Social sign-in (for example Google), where your deployment enables it.
- Single sign-on (SSO) via SAML 2.0 or OIDC connections you configure under SSO. Sign-in is email-domain-routed: enter your email and Praxis sends you to the right IdP.
- API tokens for programmatic, non-interactive access — see Using API tokens.
Each method ends in the same place: a Praxis session that carries your identity, current organization, and current tenant.
Invitation
A pending membership record that lets someone join an organization (and optionally a tenant) without already having an account. See Invitations. An invitation has a target (org or tenant), a role, an optional email address, and an expiry. Accepting it on /invitation/:token creates or links the user's account into the target.
Enforce SSO
A flag on an SSO connection that blocks password sign-in for users in the org whose email domain matches the connection. Use this to prevent local-password drift once IdP-managed sign-in is the source of truth.