> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Identity & Access Management
> Manage members, roles, groups, SSO, API keys, and service accounts
Governe provides comprehensive identity and access management (IAM) for your organization. This includes user management, role-based permissions, SSO configuration, and programmatic access through API keys and service accounts.
## Joining the Platform
Access to Prisme.ai is two-staged: a user must first have an account on the **platform**, and then become a member of one or more **organizations**. Platform access is the prerequisite — without it, organization invites and links cannot be redeemed.
A platform account is created in one of two ways:
* **Local signup** — the user signs up with an email and password. Local signup must be enabled at the platform level, and depending on configuration, new accounts may require **superadmin validation** before they become active.
* **SSO login** — the user authenticates through a configured identity provider (OIDC or SAML). The account is created automatically on first login. If the SSO provider is attached to an organization, the user is also added to that organization (see [SSO auto-join](#joining-an-organization)).
A user without a platform account who clicks an organization **invitation link** will see an authentication error — they need to sign up or log in first. To onboard a user who has no account yet, send them an **email invite** instead (see below).
## Joining an Organization
Once a user has a platform account, they can become a member of one or more organizations. Prisme.ai offers four distinct mechanisms, each with different trade-offs:
| Mechanism | Trigger | Role | Groups | Re-evaluated | Works without a pre-existing platform account? |
| -------------------------- | ------------------------------------------------------------------------ | ----------------- | --------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| **Email invite** | Admin invites a user by email; the user accepts on first login or signup | Admin-chosen role | No | No | **Yes** — the invitation prepares the membership for first connection |
| **Invitation code (link)** | User opens a shared link while authenticated | Code's `roleSlug` | No | No | **No** — the user must already be logged in |
| **Join rules** | Evaluated on every `/me` call after login | Rule's `role` | Rule's `groups` | Yes — members no longer matching are removed | Either |
| **SSO auto-join** | SSO login from a domain configured on an organization | `defaultRole` | No | Once at first login | Either |
### When to use each mechanism
* **Email invite** — invite a specific person who may not yet have an account. The invitation prepares their membership with the right role; they automatically join the organization on their first login, whether through local signup or SSO.
* **Invitation code (link)** — share a single link with a group of people so they can join the organization on their own with the right role. Invitation codes only work for users who **already have a platform account**. You can monitor the usage count and revoke a link at any time.
* **Join rules** — automatically grant organization membership based on user attributes (email domain, SSO claims, custom metadata). Best when membership should be governed by conditions you control rather than per-user actions.
* **SSO auto-join** — use when an organization has its own SSO provider; everyone authenticating via that provider becomes a member. Combine with join rules to assign granular roles or groups.
**Sharing an invitation link with someone who isn't on the platform yet?** Invitation links require the recipient to be authenticated. Either send them an **email invite** (which works without a pre-existing account), or ask them to sign up first (local signup or SSO) before clicking the link.
## Inviting Members
To invite a specific user by email:
1. Go to **Members** in the sidebar
2. Click **Invite Member**
3. Enter the user's email address
4. Select a role to assign
What happens next depends on whether the user already has a platform account:
| Situation | Outcome |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The user **already has a platform account** | They are added to the organization immediately with **Active** status and the assigned role. No email is sent. |
| The user **does not have a platform account yet** | An invitation email is sent. They appear with **Pending** status until their first login (via local signup or SSO), at which point the prepared membership is activated with the assigned role. |
For sharing access with multiple people at once via a reusable link, use [Invitation Codes](#invitation-codes) instead.
### Managing Existing Members
From the **Members** list, you can:
* **Change role** — click a member and select a new role
* **Suspend** — temporarily disable access without removing membership
* **Remove** — permanently remove the user from the organization
## Join Rules
Join rules allow automatic organization membership based on user attributes. Rules are evaluated dynamically and can assign both a role and group memberships.
### Rule Structure
Each join rule contains an array of conditions with AND logic — all conditions in a rule must match:
```json theme={null}
{
"rules": [
{ "field": "email", "operator": "endsWith", "value": "@acme.com" },
{ "field": "authData.google.hd", "operator": "equals", "value": "acme.com" }
],
"role": "member",
"groups": ["engineering", "default-access"]
}
```
An organization can have multiple join rules — they use OR logic between entries (only one rule needs to match).
**Rule order matters.** Rules are evaluated in order and the **first matching rule wins** — its `role` and `groups` are applied, and any subsequent rules that would also match are ignored. Reorder rules from the **Join Rules** screen to control precedence (e.g. put more specific rules above broader catch-all ones).
### Condition Fields
| Field | Type | Description |
| ---------- | ------ | -------------------------------------------------------------------------------------------- |
| `field` | string | Dot-notation path on the user object (e.g. `email`, `authData.google.hd`, `meta.department`) |
| `operator` | string | `equals`, `startsWith`, or `endsWith` (case-insensitive) |
| `value` | string | The value to match against |
### Creating a Join Rule
1. Go to **Join Rules** in the sidebar
2. Click **Add Rule**
3. Define conditions
4. Select the role to assign
5. Optionally select groups to add the user to
### Rule Evaluation
Join rules are evaluated on every `/me` API call (the first call the platform makes after authentication). A per-user version cache ensures rules are only re-evaluated when they change:
1. Each org's join rules have a version counter (incremented when rules are updated)
2. The gateway tracks which version was last evaluated for each user
3. If the version matches, evaluation is skipped for that org
### Re-evaluation on Rule Changes
When an organization's join rules are updated, the platform re-evaluates all existing members who joined via join rules:
* Members who **no longer match** any rule are automatically removed from the organization
* New users who now match are **not** retroactively added — they join on their next `/me` call
* Re-evaluation processes members in batches of 500
## Invitation Codes
Invitation codes let you share a link that grants access to your organization to anyone who already has a Prisme.ai account.
### Creating an Invite
1. Go to **Invites** in the sidebar
2. Click **Generate Invite**
3. Configure:
* **Role**: What role invitees receive
* **Max Uses**: Limit how many times the code can be used (optional)
* **Expiration**: When the code expires (optional)
4. Share the generated link
Recipients must be **authenticated on the platform** to redeem an invitation link. If a recipient does not have a platform account yet, use an [email invite](#inviting-members) instead, or ask them to sign up first (local signup or SSO).
### Invite Status
| Status | Description |
| ------------- | -------------------- |
| **Active** | Can still be used |
| **Expired** | Past expiration date |
| **Exhausted** | Reached max uses |
| **Revoked** | Manually disabled |
## Roles & Permissions
Roles define what actions members can perform. Each role contains a set of permissions.
For the **big picture** — how organization roles combine with super-admins and workspace roles to authorize every action on the platform — see [Self-Hosting → Permissions Management](/self-hosting/entreprise/permissions).
### Permission Format
Permissions follow a hierarchical `product:resource:action` pattern with wildcard support:
| Product | Key | Example Permissions |
| ------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization | `orgs` | `orgs:members:manage`, `orgs:groups:read`, `orgs:apikeys:create`, `orgs:branding:update`, `orgs:sso:manage`, `orgs:service-accounts:manage`, `orgs:navigation:manage`, `orgs:invites:manage`, `orgs:join-rules:manage`, `orgs:roles:read` |
| Users (Platform) | `users` | `users:read`, `users:update`, `users:delete`, `users:manage` |
| LLM | `llm` | `llm:completions:use`, `llm:embeddings:use`, `llm:governance:manage` |
| Tools | `tools` | `tools:web_search`, `tools:knowledge_search`, `tools:code_execution`, `tools:api_call` |
| Agents | `agent-factory` | `agent-factory:agents:read`, `agent-factory:agents:write`, `agent-factory:agents:delete`, `agent-factory:agents:publish`, `agent-factory:agents:share`, `agent-factory:agents:explore` |
| Storage / Knowledge | `storage` | `storage:vector_stores:read/write/share/delete`, `storage:files:read/write/delete`, `storage:skills:read/write/delete` |
| Chat | `secure-chat` | `secure-chat:*` |
| Builder | `builder` | `builder:*` |
| Governe | `ai-governance-v2` | `ai-governance-v2:observability:read`, `ai-governance-v2:observability_platform:read`, `ai-governance-v2:announcements:write` |
| Insights | `insights` | `insights:*` |
| Engage | `engage` | `engage:*` |
| Collections | `collections` | `collections:*` |
Wildcards are supported at any level: `orgs:members:*` grants all member actions, `storage:*` grants all storage permissions, `*` grants everything.
### Resource Scopes
Scopes restrict **which specific resources** a role can access, independent of permissions. They use the format `product:resource:id`:
```json theme={null}
{
"scopes": [
"agent-factory:agents:agent_abc123",
"storage:vector_stores:kb_xyz",
"llm:models:gpt-4o"
]
}
```
* `*` grants access to all resources
* `agent-factory:agents:*` grants access to all agents
* Empty or omitted scopes mean no resources are accessible
Scopes are available on both roles and [API keys](#api-keys).
### Per-resource sharing
Beyond the scopes hardcoded on a role, every resource instantiated by an **Agent Factory** or **Knowledge** project carries its own RBAC. From a project's **Share** dialog, you can grant access to specific users or groups on that one resource, picking a product-managed role (e.g. Viewer / Editor / Owner). Those product roles map to the same `product:resource:action` permissions used by organization roles.
This lets you give fine-grained access to a single agent or knowledge base **even when the user's organization role has no scope for that resource**.
**Permissions are intersected, not unioned.** An action on a resource is allowed only when the equivalent permission is granted **both** by the user's organization role **and** by their role on the resource. Granting `Editor` on a single agent does not bypass the organization role — if that role does not include `agent-factory:agents:write`, the user still cannot edit the agent.
### Built-in Roles
Organizations come with system roles that cannot be deleted:
| Role | Slug | Permissions | Scopes | Description |
| ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------- |
| **Owner** | `org:owner` | `*` | `*` | Full organization management. Cannot be overridden. |
| **Admin** | `org:admin` | `orgs:members:manage`, `orgs:groups:manage`, `orgs:branding:manage`, `orgs:navigation:manage`, `orgs:invites:manage`, `orgs:join-rules:manage`, `orgs:apikeys:manage`, `users:manage`, `secure-chat:*`, `agent-factory:*`, `builder:*`, `engage:*`, `storage:*`, `collections:*`, `insights:*`, `ai-governance-v2:*` | `*` | Organization administration |
| **Member** | `org:member` | `orgs:roles:read`, `users:read`, `orgs:groups:read`, `orgs:members:read`, `agent-factory:agents:read`, `agent-factory:agents:explore`, `storage:vector_stores:read`, `storage:files:read`, `storage:skills:read`, `secure-chat:*` | — | Basic organization member |
| **Agent Maker** | `agent-maker` | Member base + `agent-factory:*`, `storage:*`, `knowledge:*` | `*` | Full agent-factory & knowledge access |
| **Builder** | `builder` | Agent Maker + `builder:*` | `*` | Builder + agent-factory + knowledge access |
| **Agent Standard** | `agent-standard` | `llm:*`, `tools:*` | — | Default agent role (for service accounts) |
All system roles except `owner` can be customized per organization. When an admin edits a system role in the Governe UI, a custom role override is saved for that organization that fully replaces the system definition.
### Creating Custom Roles
1. Go to **Roles** in the sidebar
2. Click **Create Role**
3. Enter name and description
4. Select permissions using the **Permission Tree Editor**
The role editor displays permissions as a hierarchical tree organized by product > resource > action:
* Checking a **product** node sets the product-level wildcard (e.g. `storage:*`)
* Checking a **resource** node sets the resource-level wildcard (e.g. `storage:vector_stores:*`)
* Individual actions can be toggled independently
* For products supporting instance scoping, a **Scopes** section appears under each resource, allowing admins to set the "All resources" wildcard or add specific resource IDs
## Groups
Groups organize members for easier bulk management. Use cases include:
* Department-based access (Engineering, Marketing)
* Project teams with shared permissions
* Geographic regions
### Creating Groups
1. Go to **Groups** in the sidebar
2. Click **Create Group**
3. Enter name, slug, and optional description
4. Add members to the group
### Using Groups with Join Rules
Groups work with [Join Rules](#join-rules) to automatically add new users to the right groups based on their attributes.
## SSO Configuration
Configure Single Sign-On with your corporate identity provider.
The provider config format (OIDC / SAML, `attributesMapping`, claims, certificates, …) is **identical** to the platform-level SSO documented under [Self-Hosting → Authentication & SSO](/self-hosting/entreprise/authentication). The only difference is where you declare it: a Kubernetes ConfigMap for platform-wide SSO vs the Governance UI here for per-organization SSO. Refer to the self-hosting page for the full field-by-field reference and IdP-specific tips (Google Workspace, Okta, Auth0, Keycloak, ADFS, OneLogin, …).
### Platform SSO vs Organization SSO
| Level | Where it's configured | Who sees it | Auto-org membership |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
| **Platform SSO** | Kubernetes — `authProviders.config.yml` mounted into `prismeai-api-gateway` (see [Self-Hosting → Authentication](/self-hosting/entreprise/authentication)) | Every user on the global sign-in page | No — users authenticate but are not added to any organization |
| **Organization SSO** *(this page)* | Governance UI → **SSO** | Users matching this org's **email domain pattern** | Yes — users are auto-added to the matching organization on first login |
### Supported Providers
| Type | Examples |
| -------- | --------------------------------------- |
| **OIDC** | Google Workspace, Azure AD, Okta, Auth0 |
| **SAML** | Azure AD, Okta, OneLogin, ADFS |
### SSO Config Structure
SSO configuration is stored as part of the organization object (`ssoConfig` field):
| Field | Type | Description |
| ------------------------ | --------- | ----------------------------------------------------------- |
| `enabled` | boolean | Whether SSO is active |
| `domains` | string\[] | Email domains that trigger SSO (must be unique across orgs) |
| `provider.type` | string | `saml` or `oidc` |
| `provider.saml` | object | SAML config: `entryPoint`, `issuer`, `cert` |
| `provider.oidc` | object | OIDC config: `issuer`, `clientId`, `clientSecret` |
| `settings.enforceSSO` | boolean | Require SSO (disable local auth) |
| `settings.autoProvision` | boolean | Auto-create accounts for new SSO users |
| `settings.defaultRole` | string | Role assigned to auto-provisioned users |
| `settings.allowedRoles` | string\[] | Roles that SSO users can be assigned |
### Adding an OIDC Provider
1. Go to **SSO** in the sidebar
2. Click **Add Provider**
3. Select **OIDC**
4. Enter configuration:
| Field | Description |
| ----------------- | ------------------------------ |
| **Issuer** | Your IdP's issuer URL |
| **Client ID** | OAuth client ID from your IdP |
| **Client Secret** | OAuth client secret |
| **Scopes** | Usually `openid profile email` |
5. Configure **attribute mapping** to map IdP claims to user fields
6. Optionally restrict to specific **domains** (e.g., `@acme.com`)
7. Enable the provider
Works with Azure AD, Okta, Google Workspace, or any OIDC-compliant provider.
### Adding a SAML Provider
1. Go to **SSO** in the sidebar
2. Click **Add Provider**
3. Select **SAML**
4. Enter configuration:
| Field | Description |
| --------------- | -------------------------------------- |
| **Entry Point** | IdP's SSO URL |
| **Certificate** | IdP's signing certificate (PEM format) |
| **Audience** | Service Provider entity ID |
5. Download the SP metadata to configure your IdP
6. Enable the provider
### Domain Validation
When updating SSO config, the system validates that domains are not already claimed by another organization. If a domain conflict is found, the update is rejected with a `DOMAIN_ALREADY_USED` error.
### Secrets Encryption
SSO provider secrets (OIDC `clientSecret`, SAML certificates) are encrypted at rest using **envelope encryption** (`@prisme.ai/secrets`) when the `SECRETS_MASTER_KEYS` environment variable is configured:
* A per-organization **Data Encryption Key (DEK)** encrypts the SSO config
* The DEK is wrapped by a platform-level **Key Encryption Key (KEK)** using AES-256-GCM
* Wrapped DEKs are stored in MongoDB alongside the org; plaintext secrets are never persisted
If `SECRETS_MASTER_KEYS` is not configured, SSO configs are stored in plaintext.
## API Keys
API keys (`iak_*`) enable programmatic access to the Prisme.ai platform from external systems. They are scoped to an organization and carry specific permissions and resource scopes.
### Key Format
All API keys use the format `iak_{orgSlug}_{uuid}`:
```
iak_acme-corp_a1b2c3d4e5f6g7h8...
```
The embedded `orgSlug` allows the auth middleware to resolve the organization without a database lookup. Keys are stored **hashed** — the plaintext key is returned only once at creation time.
### Creating an API Key
1. Go to **API Keys** in the sidebar
2. Click **Create API Key**
3. Enter a name
4. Select permissions using the Permission Tree (same `product:resource:action` format as roles)
5. Optionally set **scopes** to restrict to specific resources (e.g., `agent-factory:agents:agent-abc-123`)
6. Set an expiration date if needed
The API key is only shown once when created. Store it securely.
### Scopes
Scopes restrict **which resources** a key can access, even if the permission allows the action. They use the same `product:resource:id` format as [role scopes](#resource-scopes):
```json theme={null}
{
"scopes": [
"agent-factory:agents:agent-abc-123",
"llm:models:gpt-4o",
"storage:vector_stores:kb_xyz"
]
}
```
Wildcards are supported: `agent-factory:agents:*` grants access to all agents, `*` grants access to all resources.
### Using API Keys
Include the key in the `x-prismeai-api-key` header:
```bash theme={null}
curl -H "x-prismeai-api-key: iak_acme-corp_a1b2c3d4..." \
https://api.prisme.ai/v1/completions
```
### How API Key Validation Works
API key validation is handled natively by the platform runtime. When a request includes an `iak_*` key, the runtime resolves the organization, permissions, and scopes, then injects them into the standard `run.permissions` and `run.scopes` variables — the same variables used for user session auth. No cross-workspace HTTP call is needed.
### Rotating Keys
1. Click on an API key
2. Click **Rotate**
3. A new key is generated with zero downtime — the old key is immediately invalidated
## Service Accounts
Service accounts are non-human identities for machine-to-machine authentication. Use them for:
* CI/CD pipelines
* Backend integrations
* Automated workflows
* Scheduled tasks
### Creating a Service Account
1. Go to **Agents Controls > Service Accounts**
2. Click **Create Service Account**
3. Enter:
* **Slug**: URL-safe identifier
* **Name**: Display name
* **Role**: Permission set to assign
4. Copy the generated **client secret**
The client secret is only shown once. Store it securely.
### Authenticating as a Service Account
Exchange the client credentials for an access token:
```bash theme={null}
curl -X POST https://api.prisme.ai/oauth/token \
-d "grant_type=client_credentials" \
-d "client_id=SERVICE_ACCOUNT_ID" \
-d "client_secret=CLIENT_SECRET"
```
### Managing Service Accounts
* **Enable/Disable**: Toggle access without deleting
* **View Last Used**: See when the account last authenticated
* **Rotate Secret**: Generate a new client secret
## Best Practices
Grant only the minimum permissions needed for each role
Organize members into groups for easier permission management
Regularly rotate API keys and service account secrets
Review audit logs to monitor permission changes
Automate onboarding with join rules for consistent access
Set expiration dates on invitation codes