Skip to main content
POST
Share an agent with a principal (create binding)

Authorizations

Authorization
string
header
required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Path Parameters

agentId
string
required
Maximum string length: 64

Body

application/json
principal_type
enum<string>
required
Available options:
user,
group,
org
Maximum string length: 32
principal_id
string
required

User id (or email for user type, resolved server-side), group id, or org slug. For org, the target may be the agent's own org, another org (sharer must be a member), or the literal * for all authenticated users belonging to at least one org - both beyond-own-org forms require agent-factory:sharing:cross-org.

Maximum string length: 128
role_slug
string

Role to grant, admin or user (owner is refused). Defaults to admin for same-org shares, user for any org target beyond the agent's own org.

Maximum string length: 64

Response

Binding created.

created
boolean
Example:

true

binding
object

Access binding granting a principal a role on an agent.