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

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

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

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.

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 to automatically add new users to the right groups based on their attributes.

SSO Configuration

Configure Single Sign-On with your corporate identity provider.

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:

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

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:

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