Identity & Access Management

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).

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:

Go to Members in the sidebar
Click Invite Member
Enter the user’s email address
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 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:

{
  "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).

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

Go to Join Rules in the sidebar
Click Add Rule
Define conditions
Select the role to assign
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:

Each org’s join rules have a version counter (incremented when rules are updated)
The gateway tracks which version was last evaluated for each user
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

Go to Invites in the sidebar
Click Generate Invite
Configure:
- Role: What role invitees receive
- Max Uses: Limit how many times the code can be used (optional)
- Expiration: When the code expires (optional)
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 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.

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:

{
  "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. 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

Go to Roles in the sidebar
Click Create Role
Enter name and description
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

Go to Groups in the sidebar
Click Create Group
Enter name, slug, and optional description
Add members to the group

Using Groups with Join Rules

Groups work with 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. 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)	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

Go to SSO in the sidebar
Click Add Provider
Select OIDC
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`

Configure attribute mapping to map IdP claims to user fields
Optionally restrict to specific domains (e.g., @acme.com)
Enable the provider

Works with Azure AD, Okta, Google Workspace, or any OIDC-compliant provider.

Adding a SAML Provider

Go to SSO in the sidebar
Click Add Provider
Select SAML
Enter configuration:

Field	Description
Entry Point	IdP’s SSO URL
Certificate	IdP’s signing certificate (PEM format)
Audience	Service Provider entity ID

Download the SP metadata to configure your IdP
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

Go to API Keys in the sidebar
Click Create API Key
Enter a name
Select permissions using the Permission Tree (same product:resource:action format as roles)
Optionally set scopes to restrict to specific resources (e.g., agent-factory:agents:agent-abc-123)
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:

{
  "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:

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

Click on an API key
Click Rotate
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

Go to Agents Controls > Service Accounts
Click Create Service Account
Enter:
- Slug: URL-safe identifier
- Name: Display name
- Role: Permission set to assign
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:

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

Least Privilege

Grant only the minimum permissions needed for each role

Use Groups

Organize members into groups for easier permission management

Rotate Credentials

Regularly rotate API keys and service account secrets

Audit Access

Review audit logs to monitor permission changes

Join Rules

Automate onboarding with join rules for consistent access

Expire Invites

Set expiration dates on invitation codes

​Joining the Platform

​Joining an Organization

​When to use each mechanism

​Inviting Members

​Managing Existing Members

​Join Rules

​Rule Structure

​Condition Fields

​Creating a Join Rule

​Rule Evaluation

​Re-evaluation on Rule Changes

​Invitation Codes

​Creating an Invite

​Invite Status

​Roles & Permissions

​Permission Format

​Resource Scopes

​Per-resource sharing

​Built-in Roles

​Creating Custom Roles

​Groups

​Creating Groups

​Using Groups with Join Rules

​SSO Configuration

​Platform SSO vs Organization SSO

​Supported Providers

​SSO Config Structure

​Adding an OIDC Provider

​Adding a SAML Provider

​Domain Validation

​Secrets Encryption

​API Keys

​Key Format

​Creating an API Key

​Scopes

​Using API Keys

​How API Key Validation Works

​Rotating Keys

​Service Accounts

​Creating a Service Account

​Authenticating as a Service Account

​Managing Service Accounts

​Best Practices

Least Privilege

Use Groups

Rotate Credentials

Audit Access

Join Rules

Expire Invites

Joining the Platform

Joining an Organization

When to use each mechanism

Inviting Members

Managing Existing Members

Join Rules

Rule Structure

Condition Fields

Creating a Join Rule

Rule Evaluation

Re-evaluation on Rule Changes

Invitation Codes

Creating an Invite

Invite Status

Roles & Permissions

Permission Format

Resource Scopes

Per-resource sharing

Built-in Roles

Creating Custom Roles

Groups

Creating Groups

Using Groups with Join Rules

SSO Configuration

Platform SSO vs Organization SSO

Supported Providers

SSO Config Structure

Adding an OIDC Provider

Adding a SAML Provider

Domain Validation

Secrets Encryption

API Keys

Key Format

Creating an API Key

Scopes

Using API Keys

How API Key Validation Works

Rotating Keys

Service Accounts

Creating a Service Account

Authenticating as a Service Account

Managing Service Accounts

Best Practices