Consumer Security

This page specifies the authorization model applied to consumer-facing project and agent retrieval, exposed via the /api/v2/project REST endpoints (see Project and Agent API) and execution via /socket/pipeline (plain web socket) or /socket.io (Socket.IO) endpoints. It covers identity requirements, identity provider verification, external-role authorization, and agent visibility+executability rules.

Project Identity Modes

Each project in platform declares its user identity requirements through isIdentityRequired and identityProviders properties.

Mode isIdentityRequired identityProviders Client behavior when Project is open

Mode	`isIdentityRequired`	`identityProviders`	Client behavior when Project is open
Not required	`false`	empty	The user is not prompted to sign in. The user’s identity is anonymous and bound to the device via `deviceRef`; it does not carry over to another device.
Optional	`false`	one or more providers	The client offers sign-in through one of the listed identity providers when the project is opened, with an option to skip and sign in later. An anonymous caller is granted the same access as in `Not required` mode; a caller that does sign in must use one of the listed providers, or permission to run or list agents is denied (see Identity Provider Claim Matching).
Required	`true`	one or more providers	The client requires sign-in through one of the listed identity providers before the user can proceed.

Not required

false

empty

The user is not prompted to sign in. The user’s identity is anonymous and bound to the device via deviceRef; it does not carry over to another device.

Optional

false

one or more providers

The client offers sign-in through one of the listed identity providers when the project is opened, with an option to skip and sign in later. An anonymous caller is granted the same access as in Not required mode; a caller that does sign in must use one of the listed providers, or permission to run or list agents is denied (see Identity Provider Claim Matching).

Required

true

one or more providers

The client requires sign-in through one of the listed identity providers before the user can proceed.

Identity Provider Claim Matching

Whenever a project declares one or more identityProviders, the requesting identity’s provider is checked against them before permission to run or list the project’s agents is granted.

The provider of the requesting identity is resolved as follows:

For a JWT-authenticated identity, the idpRef claim carried by the token.
For a Basic-authenticated identity, the idpRef stored on the matching basic identity record.
For a request without an authenticated identity, there is no idpRef (null).

Permission to run or list agents is granted without any further identity provider check when any of these holds:

project.identityProviders is empty (no provider restriction configured), or
the resolved idpRef is the reserved value pai-internal, identifying a fully trusted internal caller, or
project.isIdentityRequired is false and the request has no authenticated identity at all (and consequently no idpRef) — a fully anonymous caller is treated the same as in Not required mode.

Otherwise, the resolved idpRef must match the ref of one of project.identityProviders. This applies both to a project in Required mode and to any authenticated caller of a project in Optional mode — only a fully anonymous (unauthenticated) caller is exempt from the match in Optional mode. If the idpRef does not match, permission to run or list agents is denied (see Agent State Visibility), independent of isUsingExternalRoles.

Only once the identity provider match succeeds is the optional external-role check, described below, evaluated.

Optional External Role Authorization

A project may additionally restrict permission to run or list agents to identities holding a specific external role, controlled by its isUsingExternalRoles property. This check is evaluated only after the identity provider match described in Identity Provider Claim Matching has succeeded.

When isUsingExternalRoles is set to true, permission is granted only if an AccessControlList record exists, scoped to the project or to its owning tenant, that matches the requesting identity by either of the following:

the record’s userId matches the caller’s internal user id (any ACL role qualifies), or
the record’s externalIdentity.idpRef matches the identity provider (idpRef) claim of the identity used to authenticate the request, and its externalIdentity.role is either null or is contained in the extRoles claim of the identity.

If no such record exists, permission to run or list agents is denied. If a matching record is found — or isUsingExternalRoles is false — the project’s data including agents is returned according to the visibility rules described below.

If a project is returned without any agents because the requesting identity is not permitted to run agents there, the client shows a message such as "You do not have any agents available in this project. Reload this screen later or contact project administrator."

Agent State Visibility

When sign in is performed OR identity is not required, the project’s agents list property returns agent revisions according to their state, subject to the requesting identity’s permission to run agents (Identity Provider Claim Matching and, where applicable, external role authorization) and its ACL role on the project or tenant:

Agent.state Visibility

`Agent.state`	Visibility
`Published`	Visible to every identity permitted to run agents in the project — except a `TestAgent`, which is never included in this listing regardless of state; see Test Agents.
`Preview`	Visible to every identity permitted to run agents in the project that also holds an ACL record (any role) on the project or its tenant — no direct reference required. Additionally, when the agent is referenced directly by the `agentRef` (or `agentKey`/`agentId`) parameter — typically through an `/a/{agentRef}` link — it is included unconditionally, regardless of permission to run agents (identity provider match or external-role authorization) and regardless of ACL role, as long as either the project does not require identity or the caller is authenticated.
`Draft`	Visible to every identity permitted to run agents in the project that also holds an `Owner` or `Editor` ACL record on the project or its tenant — no direct reference required. Additionally, when referenced directly by the `agentRef` (or `agentKey`/`agentId`) parameter, it is included for any identity holding an ACL record of any role on the project or its tenant, regardless of permission to run agents.
`Archived`	Visible only when referenced directly by the `agentRef` (or `agentKey`/`agentId`) parameter, and only for an identity holding an ACL record of any role on the project or its tenant, regardless of permission to run agents.

Published

Visible to every identity permitted to run agents in the project — except a TestAgent, which is never included in this listing regardless of state; see Test Agents.

Preview

Visible to every identity permitted to run agents in the project that also holds an ACL record (any role) on the project or its tenant — no direct reference required.

Additionally, when the agent is referenced directly by the agentRef (or agentKey/agentId) parameter — typically through an /a/{agentRef} link — it is included unconditionally, regardless of permission to run agents (identity provider match or external-role authorization) and regardless of ACL role, as long as either the project does not require identity or the caller is authenticated.

Draft

Visible to every identity permitted to run agents in the project that also holds an Owner or Editor ACL record on the project or its tenant — no direct reference required.

Additionally, when referenced directly by the agentRef (or agentKey/agentId) parameter, it is included for any identity holding an ACL record of any role on the project or its tenant, regardless of permission to run agents.

Archived

Visible only when referenced directly by the agentRef (or agentKey/agentId) parameter, and only for an identity holding an ACL record of any role on the project or its tenant, regardless of permission to run agents.

Sharing Drafts With an External Organization

An externalIdentity ACL record can satisfy the Draft direct-reference rule above, letting a customer’s staff test a Draft agent via a shared link without adding each person as a project member:

Set project.isUsingExternalRoles to true.
Ensure the customer’s identity provider is listed in project.identityProviders.

Add one AccessControlList record, scoped to the project or its tenant:

{
  "externalIdentity": { "idpRef": "<customer-idp-ref>", "role": null },
  "role": "Consumer"
}

Anyone authenticating through <customer-idp-ref> now satisfies the "any ACL role" requirement for direct-referenced Drafts — no per-person membership needed. This grants access to the customer’s whole organization on that provider, not one individual; for narrower scoping, set externalIdentity.role to a specific value the identity provider actually issues as a claim. It does not unlock Drafts in the regular listing — only the direct link; browsing Drafts still requires Owner/Editor.

Test Agents

An agent implemented as a TestAgent (used to simulate a counterpart persona for roleplay or training rather than to serve real end users) must remain in Published state to be executable, but is excluded from every ordinary agent listing — regardless of state, of the requesting identity’s permission to run agents, and of its ACL role.

A TestAgent is reachable only when referenced directly by the agentRef (or agentKey/agentId) parameter — e.g. a QR-code deep link — and only for an identity holding an Owner or Editor ACL record on the project or its tenant. Any other identity, including one that would otherwise see every Published, Preview, and Draft agent in the project, gets no indication that a TestAgent exists.

Direct Agent Reference Resolution

A project can be retrieved by reference to one of its agents, using agentRef, agentKey, or agentId parameter on /api/v2/project endpoint (see Project and Agent API).

A plain reference (ref, key, or id without a revision suffix) resolves only to an agent whose state is Published.
A revision-qualified reference (in ref.revision or id.revision format) resolves to the exact agent revision regardless of its state.

The agent revision resolved by its reference is included in the project’s agents property according to the visibility rules specified in the previous section.