Identity & Access Management

Identity and access is the first cross-cutting concern the unified foundation handles once for everyone: SSO and centralized permissions flow from here to every product, rather than being reinvented in each silo. Governe provides comprehensive identity and access management (IAM) for your organization, including 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, for users who are not yet members	Rule’s `role`	Rule’s `groups`	When the rules change, to remove members who no longer match. An existing member’s role and groups are only updated on demand, by re-evaluating the rules	Either
SSO auto-join	SSO login from a domain configured on an organization	The matching join rule’s `role`, else `defaultRole`	The matching join rule’s `groups`	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.

Creating an Organization

A guided setup creates an organization and makes it usable in a few minutes: its name and logo, its colors, the apps in its menu and who joins it automatically.

Who can create an organization

Who	How they get the right	Limit
Platform administrators (`superadmin`, `root`)	Platform role	None
Organization creators (`org-creator`)	Platform role granted to a user by a platform administrator, from Platform > Users	`ORGS_MAX_PER_CREATOR` organizations per person (3 by default)
Self-service users	Platform setting `ORGS_SELF_SERVICE`	Same limit as organization creators

Self-service creation is a platform-level setting (self-hosted deployments set it as an environment variable of the API gateway):

`ORGS_SELF_SERVICE`	Who can create an organization
`off` (default)	Only platform administrators and organization creators
`domains`	Signed-in users whose email domain is listed in `ORGS_SELF_SERVICE_DOMAINS` (comma separated, e.g. `acme.com,acme.fr`)
`open`	Any signed-in user

Anonymous sessions can never create an organization. Setting ORGS_MAX_PER_CREATOR to 0 removes the limit. The person who creates an organization becomes its Owner.

The guided setup

Users allowed to create an organization can start it from the organization switcher, on the welcome screen shown to a user who belongs to no organization yet, or from AI Governance > Organizations. The setup runs in four steps, with a live preview of the result:

Identity: the organization name, its identifier (used in URLs) and its logo.
Appearance: a color palette, suggested from the logo or picked from presets.
Use cases: the apps that make up the menu of the organization (chat, agents, knowledge, governance and so on).
Access: an optional join rule on the creator’s own email domain, with the role new members receive. When the creator’s current organization already has allowed AI models, the setup offers to reuse them.

Nothing is created before the last step is confirmed. The organization then becomes the creator’s active organization, and the final screen links to what usually comes next: opening the chat, configuring the AI models, setting up SSO, inviting the team and connecting the Builder.

If a part of the setup cannot be applied (for example a join rule the platform refuses), the organization is still created and the final screen offers to retry that part only.

Inviting Members

To invite a specific user by email:

Go to Members in the sidebar
Click Invite Member
Start typing a name or an email address. The field autocompletes against the platform’s users, so an existing account can be picked from the list instead of being retyped
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. When a user joins through a rule, they receive the rule’s 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).

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	User attribute to match: `email`, `firstName`, `lastName`, `groups`, or a dot-notation path under `authData` (identity provider claims, e.g. `authData.google.hd`, `authData.okta.department`) or `meta` (e.g. `meta.department`). Any claim name is accepted, as long as it contains no dot.
`operator`	string	`equals`, `startsWith`, `endsWith`, `matches` (wildcard pattern, `*` matches any characters) or `contains` (element of an array, or substring of a string)
`value`	string	The value to match against, case-insensitive, up to 512 characters

Rules can only match the attributes listed above. A rule on any other user field (credentials, platform role…) is rejected when saved, and a rule saved before this restriction no longer matches anyone.

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

Who can add which rules

A join rule makes every matching user a member at their next login, so an unrestricted rule would let any organization owner pull a whole company into an organization they control. Outside platform administrators, a rule that is added or changed must therefore:

Target the author’s own company. One condition of the rule must be anchored on the identity of the person saving it: email endsWith their own email domain (@acme.com), email equals an address of that domain, or their own SSO tenant (authData.azure.tid or authData.google.hd equals their value). The other conditions are combined with AND, so they can only narrow the rule. Public mailbox domains (gmail.com, outlook.com and the like) are never accepted.
Name the role it grants. A rule without a role is refused: the role members receive is the one written in the rule.
Grant a role that does not manage the organization. Owner, Admin and any custom role holding * or an orgs:...:manage permission cannot be granted to a whole domain.

Rules already in place are left untouched, and removing a rule is always allowed. For the same reason, the organization’s default role cannot be changed to a managing role while rules without a role still rely on it. To add the domain of another company (a customer, a partner), invite an administrator of that company: they can add the rule on their own domain from their account. A platform administrator can also add any rule.

Importing and exporting rules

The Join Rules tab reads and writes its whole ruleset as JSON. Export downloads the current rules, Import applies a file to the organization. The same import and export exists on Agents Controls and, with a multiselect, on Capabilities, so a governance setup validated in one organization or environment can be replayed in another instead of being re-entered rule by rule.

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

Join rules grant membership; they do not keep it in sync. A user who is already a member of the organization is skipped, whatever way they joined. Their role and groups stay as they were, even if their SSO attributes changed since (for example after being added to an identity-provider group). To change an existing member’s access, change their role from the Members list, or re-evaluate the rules on the existing members. For a rule to set the role on arrival, make sure the user’s attributes are in place before their first login to the organization.

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, unless you apply the rules right away (see below)
Re-evaluation processes members in batches of 500

On a rule change, only members who joined through a join rule are re-evaluated. Members added by an invitation, an invitation code, SSO auto-join or by an administrator are never removed by a rule change. Re-evaluating the rules with existingMembers: "all" also evaluates them, only to update their role and groups. For a member who joined through a join rule, a rule change has two possible outcomes:

The member…	Result
still matches at least one rule	Stays in the organization with the same role and groups, even if the rule that now matches first assigns other groups or another role
no longer matches any rule	Is removed from the organization

A rule change on its own only assigns a rule’s role and groups when the user joins the organization. To bring existing members in line with a new ruleset, re-evaluate the rules with the existingMembers option, or update them from the Members and Groups screens.

Simulating and applying rules

Before saving a ruleset, you can measure its impact with POST /v2/orgs/{orgSlug}/join-rules/apply. It requires the orgs:join-rules:manage permission and runs as a dry run by default: nothing is written. From the interface, the Re-evaluate button of the Join Rules screen runs it on the saved rules: the simulation is checked by default and lists the members to remove, the members to update and the users who would join. Unchecking it starts the apply in the background. Saving the rules already removes the members who no longer match them (see Re-evaluation on Rule Changes): on saved rules, the members to remove are only those whose attributes changed since, for example an SSO claim.

curl -X POST "$API_URL/v2/orgs/acme/join-rules/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "joinRules": [
      { "rules": [{ "field": "authData.acme.code", "operator": "startsWith", "value": "R/1/2/" }], "groups": ["team-12"] },
      { "rules": [{ "field": "authData.acme.code", "operator": "startsWith", "value": "R/1/" }] }
    ]
  }'

Body field	Description
`joinRules`	Candidate ruleset. When omitted, the organization’s current rules are evaluated.
`dryRun`	`true` by default. Set to `false` to apply the rules.
`sampleLimit`	Number of users listed in each sample of the response (default 1000, max 2000). It never limits the processing.
`existingMembers`	Which current members are brought in line with the rules: `none` (default, they are left as they are), `join-rule` (those who joined through a join rule) or `all` (also those added by an administrator, an invitation or SSO auto-join). Other than `none`, it also requires `orgs:members:manage`, plus `orgs:groups:members:manage` when a rule sets groups. See Updating existing members.

The dry run response reports:

rulesDiff: rules added, removed or moved compared to the current ruleset
shadowedRules: rules that can never apply because an earlier rule already matches every user they would match, for example a short prefix placed above a longer one
members: current members who joined through a join rule and would be removed
joiners: users who are not members yet and would join, with the number per rule and, for each listed user, the rule that matches first, the role and the groups they would get. Anonymous, pending and deactivated users are ignored.
updates (with existingMembers other than none): current members whose role or groups would change, with the number per rule and, for each listed member, the rule that matches first, the role change (from, to) and the groups added and removed. skipped counts the members who would have changed but manage the members or the join rules.

A platform administrator acts on every platform user. An organization administrator only acts on users who belong to no organization yet, counts included. Users of other organizations who match the rules still join at their next login, as with any join rule. For organization administrators, the endpoint is also rate limited (RATE_LIMIT_JOIN_RULES_APPLY calls per minute, 5 by default).

With "dryRun": false, the candidate rules are saved and the response comes back right away with applied.status: "started". The apply then runs in the background: it removes the members who no longer match, updates the existing members in the existingMembers scope, then adds every matching user without waiting for their next login. Its outcome (members removed, members updated, users added in total and per rule, failures) is recorded in the organization’s audit log as join_rules_applied. Dry runs are recorded too, as join_rules_simulated. Only one apply runs at a time per organization: a second call meanwhile is refused with a 409. Calling it again afterwards is safe, since users who are already members are skipped. An apply interrupted by a restart is therefore completed by a new call.

Updating existing members

By default, applying the rules never changes the members already in the organization, other than removing the ones who joined through a join rule and no longer match. With existingMembers set to join-rule or all, each member in that scope who matches a rule is brought in line with the first rule they match, as a new member would be:

The matching rule…	Effect on the member
sets a `role`	The member gets that role
sets no `role`	The member’s role is left as it is
sets `groups`	The member’s groups are replaced by the rule’s: they are added to the missing ones and removed from all the others, including groups an administrator added them to
sets no `groups`	The member’s groups are left as they are

Members whose role can change the members or the join rules (any permission granting it, such as *, orgs:*, orgs:members:manage, orgs:members:update or orgs:join-rules:manage, which includes owners and administrators) are never updated: they are only counted in skipped, as are members whose role changed while the apply was running. Members added by an administrator, an invitation or SSO auto-join are never removed, even with all. The member keeps the way they joined: a member who joined through a join rule can still be removed by a later rule change.

With all, the role and groups of members added by hand are replaced by those of the rule they match. Run a simulation first and check the updates it reports.

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`
LLM Gateway	`llm-gateway`	`llm-gateway:models:read`, `llm-gateway:models:chat-completions`, `llm-gateway:models:audio-transcriptions`
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`, `agent-factory:traces:read`, `agent-factory:sharing:cross-org`, `agent-factory:apikeys:read/create/delete`
Storage / Knowledge	`storage`	`storage:vector_stores:read/write/share/delete`, `storage:files:read/write/delete`, `storage:skills:read/write/delete`, `storage:apikeys:read/create/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:*`
AI Collection	`ai-collection-v3`	`ai-collection-v3:collections:read/write/share/delete`, `ai-collection-v3:apikeys:read/create/delete`

Wildcards are supported at any level: orgs:members:* grants all member actions, storage:* grants all storage permissions, * grants everything.

agent-factory:traces:read gates reading an answer’s execution trace — the prompts, retrieved content and payloads a turn exchanged. It lives in its own traces resource, deliberately separate from the agent-editing permissions: someone allowed to change an agent is not thereby allowed to read its traffic. It is therefore not covered by the agent-factory:agents:* wildcard — it must be granted on purpose. Organization Owners hold it through *, and it is granted to Admins by default.

agent-factory:sharing:cross-org gates sharing an agent beyond its own organization — with a specific other organization the sharer belongs to, or with all authenticated users (“All”). Same pattern as traces:read: its own sharing resource, not covered by agent-factory:agents:*, so editing agents never silently implies exposing them outside the organization. Owners hold it through *, Admins through agent-factory:*; every other role must receive it explicitly in the role editor (“Share Agents Across Organizations”).

The apikeys resource of each product (agent-factory, storage, ai-collection-v3) controls the API keys of its agents, knowledge bases or collections, on top of the share permission on that resource, resource owner included:

Action	Permission
List the keys	`<product>:apikeys:read`
Create a key, rotate a key	`<product>:apikeys:create`
Revoke a key	`<product>:apikeys:delete`

Like traces:read, apikeys is its own resource, not covered by agent-factory:agents:*: an administrator can let a role share agents without letting it manage keys that bill the organization. Owners hold it through *, Admins through their product wildcards, and the Agent Maker and Builder roles receive agent-factory:apikeys:* (they already hold storage:*). Keep delete wherever keys can be created, so a leaked key can always be revoked.

After upgrading, some roles and keys lose access to the API keys of agents, knowledge bases and collections until an administrator grants the new permissions:

custom roles, and system roles your organization has already edited (their saved version replaces the system definition): check the API Keys permissions under the product in the role editor;
roles declared through ORG_ADDITIONAL_SYSTEM_ROLES on self-hosted deployments: add the permissions to the variable (<product>:apikeys:* grants them all);
organization API keys and service accounts whose scopes are limited to resources of the product (for example agent-factory:agents:* or storage:vector_stores:*), including app instances configured with such a key: they can no longer create, rotate or revoke keys until they get the <product>:apikeys:* scope and the matching permissions.

llm-gateway:models:audio-transcriptions lets a member use speech-to-text, which powers chat dictation. The system Member, Agent Maker and Builder roles grant it by default. When the platform or the organization has a transcription model, remove it from a role to turn dictation off for its holders, in every browser. When there is no transcription model at all, it is not checked: desktop Chrome and Edge dictate with the browser’s own speech service, unless the fallback is turned off. See Dictate a message → For administrators. Which transcription model they can use still follows the organization’s allowed models.

Custom roles do not get this permission automatically. Holding llm-gateway:models:read or llm-gateway:models:chat-completions does not grant it. The same applies to a system role your organization has already edited, since its saved version replaces the system definition. To let the holders of such a role dictate, edit the role and check Use Audio Transcriptions under LLM Gateway.

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 Creator 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:roles:read`, `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:`, `ai-collection-v3:`, `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:*`, `llm-gateway:models:audio-transcriptions`	-	Basic organization member
Agent Maker	`agent-maker`	Member base + `agent-factory:agents:`, `agent-factory:apikeys:`, `storage:*`	`*`	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)

Reading roles and managing them are two different permissions. Every member carries orgs:roles:read, which is what the Governe interface needs to load the roles list, so an Admin missing it used to be locked out of Governe entirely. Creating, updating or deleting an organization role requires orgs:roles:manage: being able to read the roles never implies being able to rewrite them.

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.

Additional Configuration (JSON)

The form covers the fields most providers need. Any other OIDC setting goes in the Additional Configuration (JSON) section at the bottom of the provider dialog: paste a JSON object there and it is merged into the provider configuration. The most frequent use is userinfo_endpoint. Some identity providers issue a minimal token and keep the profile attributes (first name, last name, …) on their /userinfo endpoint instead. The symptom is recognisable: users sign in successfully, but appear without a name in the members list. To fix it, paste:

{
  "userinfo_endpoint": "https://idp.example.com/oidc/userinfo"
}

Then set the attribute mapping to the claim names that endpoint actually returns, for example:

User field	IdP attribute
`firstName`	`firstname`
`lastName`	`lastname`
`email`	`email`

Existing members do not need to be removed and re-invited: their name and email are refreshed from the identity provider at every sign-in, so the values appear at their next login.

userinfo_endpoint must be an https:// URL, and your IdP must return an access token alongside the identity token (standard OIDC behaviour). If the endpoint is slow or unavailable, sign-in still succeeds and the user is simply created without the missing attributes. See Reading profile claims from the userinfo endpoint for the full behaviour and the complete list of settings accepted here.

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

If your IdP requires signed requests, enable Sign Authentication Requests (see below)
Save, reopen the provider and click Download SP Metadata to configure your IdP
Enable the provider

Signing authentication requests

When your IdP metadata contains WantAuthnRequestsSigned="true", the IdP rejects any authentication request that Prisme.ai does not sign. Enable Sign Authentication Requests on the provider and save:

A 2048-bit RSA key pair and a self-signed certificate (valid 10 years) are generated and stored in the provider configuration. Requests are signed with RSA-SHA256, with a SHA-256 digest.
The private key is never displayed nor returned by the API. Saving the provider again keeps it.
The provider dialog shows the certificate and its expiration date. Register it on your IdP, or send it the service provider metadata (Download SP Metadata), which includes it and declares AuthnRequestsSigned="true". The metadata is also available at https://API_URL/v2/login/saml/<provider-slug>/metadata.
Turning the toggle off stops signing but keeps the key: turning it back on reuses the same certificate.
Regenerate Certificate replaces the key pair immediately and is recorded in the audit log. Sign-in through the provider fails until the new certificate is registered on the IdP, so coordinate the rotation with its administrator.

To use a key issued by your own PKI instead, send privateKey and publicCert (PEM) together with signAuthnRequests: true in a PUT /v2/orgs/{orgSlug}/auth/sso/{slug} request: they must match, otherwise the save is rejected. The Additional Configuration (JSON) section only works for this on a provider that has no certificate yet, since the form keeps sending the stored one. See Signing authentication requests for the full field reference.

Request binding

Request Binding sets how the browser carries the authentication request to the IdP:

HTTP-POST (form submission), the default: the request is submitted to the IdP in a form.
HTTP-Redirect (request in the URL): the browser is redirected to the IdP with the request in the URL.

Choose HTTP-Redirect if the IdP only accepts it, or if the sign-in fails on the IdP with a 400 such as “Request contains insufficient information to determine the protocol binding” while the browser shows a GET to the IdP without SAMLRequest: a proxy in front of the IdP is then likely losing the form submission. Save the provider for the change to apply. With HTTP-Redirect, Skip Request Compression is turned off and disabled: the standard requires redirected requests to be compressed. Changing the binding of a saved provider keeps its Entry Point URL, and the form shows a warning. If the IdP declares a different SSO URL for each binding, empty the Entry Point URL field and paste the IdP metadata again so that the URL matching the binding is used. See Request binding.

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. They are also the mechanism behind the platform’s core principle that every agent is a service account with its own role, model, and tool restrictions. 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

​Creating an Organization

​Who can create an organization

​The guided setup

​Inviting Members

​Managing Existing Members

​Join Rules

​Rule Structure

​Condition Fields

​Creating a Join Rule

​Who can add which rules

​Importing and exporting rules

​Rule Evaluation

​Re-evaluation on Rule Changes

​Simulating and applying rules

​Updating existing members

​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

​Additional Configuration (JSON)

​Adding a SAML Provider

​Signing authentication requests

​Request binding

​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

Creating an Organization

Who can create an organization

The guided setup

Inviting Members

Managing Existing Members

Join Rules

Rule Structure

Condition Fields

Creating a Join Rule

Who can add which rules

Importing and exporting rules

Rule Evaluation

Re-evaluation on Rule Changes

Simulating and applying rules

Updating existing members

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

Additional Configuration (JSON)

Adding a SAML Provider

Signing authentication requests

Request binding

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