enterprise_ai.delegation
Source: sdks/python/src/enterprise_ai/delegation/__init__.py. Back to the Python SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class ExecutionContextClient
/v1/context: signed execution contexts and their signing keys.
Resource
ExecutionContextClient.issue
issue(audience: str | None = None, delegation_id: str | None = None, run_id: str | None = None, ttl_seconds: int | None = None, **extra: Any) -> Any
Issue a signed execution context. Builds and signs an ExecutionContext for the caller and returns token, context_id, kid, alg, issued_at and expires_at (201). - With run_id: the caller must have created the run, be its root principal or the user it acts for, or hold agent, tenant_admin or security_officer (403 forbidden); the delegation of the run is checked again and the agent manifest is included. - With delegation_id: the delegation must be valid and the caller one of its parties, or agent or tenant_admin. Errors: 400 context_wrong_audience for an audience the platform does not accept, 400 context_ttl_exceeded, 403 delegation_expired, 503 context_authority_unavailable. Audited as context.issue.
Route: /v1/context/issue (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
audience | str | None | None | no | Services the context is for (1 to 10), among the audiences the platform accepts. Default: the platform audiences. |
delegation_id | str | None | None | no | Delegation the context carries. Ignored when run_id is given. |
run_id | str | None | None | no | Agent run the context is for; its delegation and agent are included. |
ttl_seconds | int | None | None | no | Lifetime in seconds (30 to 86400 by the schema, and never above the platform maximum, 3600 by default). Default: 900. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Issue a signed execution context".
Raises: the typed errors of the transport (Errors).
ExecutionContextClient.jwks
jwks() -> Any
Get the public verification keys. Public verification keys as a JWKS (active, and retired ones still inside their verification window), each with kid, alg (ES256 or EdDSA) and use: sig. Any authenticated principal may read it. 503 context_authority_unavailable when the key registry cannot be read.
Route: /v1/context/jwks (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "Get the public verification keys".
Raises: the typed errors of the transport (Errors).
ExecutionContextClient.keys
keys() -> Any
List the signing keys. Registry of the context signing keys: kid, algorithm, status, dates of use, retirement and revocation. Needs security_officer or auditor. 503 context_authority_unavailable when the registry cannot be read.
Route: /v1/context/keys (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "List the signing keys".
Raises: the typed errors of the transport (Errors).
ExecutionContextClient.revoke
revoke(context_id: str) -> Any
Revoke an execution context. Revokes an issued context before it expires; verifying it then answers context_revoked. Allowed for the principal that issued it, or tenant_admin or security_officer (403 forbidden). Revoking twice keeps the first date. 404 context_not_found. Audited as context.revoke.
Route: /v1/context/{context_id}/revoke (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
context_id | str | yes | Identifier (UUID) of the context, the jti claim of its token. |
Returns: Any. Decoded JSON answer of the operation "Revoke an execution context".
Raises: the typed errors of the transport (Errors).
ExecutionContextClient.revoke_key
revoke_key(kid: str, reason: str) -> Any
Revoke a signing key. Revokes a context signing key at once: the contexts it signed no longer verify. Needs platform_admin. 404 signing_key_not_found. Audited as context.key.revoke at platform level.
Route: /v1/context/keys/{kid}/revoke (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kid | str | yes | Key id, the RFC 7638 thumbprint of the public key. | |
reason | str | yes | Why the key is revoked (3 to 2000 characters). |
Returns: Any. Decoded JSON answer of the operation "Revoke a signing key".
Raises: the typed errors of the transport (Errors).
ExecutionContextClient.verify
verify(token: str, audience: str | None = None) -> Any
Verify a signed execution context. Checks a token and returns valid, context_id, kid, alg, the claims and the context document. Checks, in order: structure and canonical form (context_malformed), algorithm and signature (context_invalid_signature), known non revoked key (context_unknown_key), issuer (context_wrong_issuer), audience (context_wrong_audience), lifetime (context_expired), tenant of the caller (403 context_tenant_mismatch), issuance record (context_revoked), digest of the document and delegation chain (a revoked delegation gives context_revoked). Refusals answer 401 unless stated and are audited; a success binds the verified identity to the audit events of the request.
Route: /v1/context/verify (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
token | str | yes | The JWS compact token (10 to 65536 characters). | |
audience | str | None | None | no | Audience the verifier expects (up to 200 characters). Default: the first platform audience. |
Returns: Any. Decoded JSON answer of the operation "Verify a signed execution context".
Raises: the typed errors of the transport (Errors).
Class DelegationsClient
/v1/delegations: scoped, time bound delegations between principals.
Resource
DelegationsClient.authorize
authorize(action: str, delegation_id: str | None = None, scope: str | None = None, resource: str | None = None, relation: str | None = None, audience: str | None = None, data_classification: str | None = None, run_id: str | None = None) -> Any
Authorize an action under a delegation. Computes the effective permission of an action: user AND agent AND delegation AND resource restriction AND relationship (OpenFGA or the builtin tuples) AND policy (OPA or builtin). Give delegation_id, or run_id to use the delegation of a run (400 invalid_request without either; 403 delegation_required for a run without delegation).
Route: /v1/delegations/authorize (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
action | str | yes | Action, dotted lowercase name such as tool.call or model.invoke, 3 to 200 characters. | |
delegation_id | str | None | None | no | Delegation to check. Give it or run_id. |
scope | str | None | None | no | Scope the action needs, at most 200 characters. |
resource | str | None | None | no | Resource acted on, <type>:<id> such as tool:crm.search, at most 300 characters. |
relation | str | None | None | no | ReBAC relation checked on the resource, for example viewer. |
audience | str | None | None | no | Service that will receive the call, at most 200 characters. |
data_classification | str | None | None | no | Classification of the data handled: public, internal, confidential, restricted or secret. |
run_id | str | None | None | no | Run whose delegation is checked, instead of delegation_id. |
Returns: Any. Decoded JSON answer of the operation "Authorize an action under a delegation".
Raises: the typed errors of the transport (Errors).
DelegationsClient.create
create(delegate: str, scopes: list[str] | None = None, audience: str | None = None, resources: list[str] | None = None, purpose: str | None = None, ttl_seconds: int | None = None, expires_at: str | None = None, max_depth: int | None = None, redelegation_allowed: bool | None = None, data_classification_max: str | None = None, session_id: str | None = None, **extra: Any) -> Any
Create a delegation. Creates a root delegation from the caller to a delegate. Open to members of the tenant; an agent cannot create a root delegation by itself (403 delegation_root_forbidden).
Route: /v1/delegations (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
delegate | str | yes | Who receives the rights: agent:<name>, app:<id>, service:<name> or subagent:<name>, 3 to 250 characters. | |
scopes | list[str] | None | None | no | Scopes delegated, at most 100. Patterns where * matches any sequence (letters, digits and _ . : / @ * -, at most 200 characters each); each must be covered by the caller scopes. |
audience | str | None | None | no | Services that may accept the delegation, at most 20 patterns. Default eai-control-plane. |
resources | list[str] | None | None | no | Resources the delegate may act on, at most 100 patterns such as tool:crm.*. Default *. |
purpose | str | None | None | no | Purpose of the delegation, at most 2000 characters, kept in the trail. |
ttl_seconds | int | None | None | no | Lifetime in seconds, at least 60, within the platform maximum. Default: the platform default (8 hours). |
expires_at | str | None | None | no | Expiry date and time (ISO 8601), instead of ttl_seconds. |
max_depth | int | None | None | no | How many levels of sub-delegation are allowed below, 0 to 10 (default 0). |
redelegation_allowed | bool | None | None | no | When true and max_depth is above 0, the delegate may restrict the delegation for others (default false). |
data_classification_max | str | None | None | no | Highest data classification the delegate may handle: public, internal, confidential, restricted or secret. Default: the caller clearance. |
session_id | str | None | None | no | Session the delegation is bound to, optional. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Create a delegation".
Raises: the typed errors of the transport (Errors).
DelegationsClient.get
get(delegation_id: str) -> Any
Get a delegation. Returns the delegation with the verification of its chain from the root (every link active, not expired, same tenant, covered by its parent). Visible to its root, creator and the person acted for, and to tenant_admin, security_officer, auditor and agent; otherwise 404 delegation_not_found.
Route: /v1/delegations/{delegation_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
delegation_id | str | yes | Identifier (UUID) of the delegation. |
Returns: Any. Decoded JSON answer of the operation "Get a delegation".
Raises: the typed errors of the transport (Errors).
DelegationsClient.list
list(status: str | None = None, root_principal_id: str | None = None, **page: Any) -> Any
List the delegations. Lists delegations, newest first, paginated: all of them for tenant_admin, security_officer and auditor, otherwise those the caller is the root, the creator or the person acted for. An unknown status answers 400.
Route: /v1/delegations (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
status | str | None | None | no | active (not expired), expired or revoked. |
root_principal_id | str | None | None | no | Only the delegations rooted at this principal. |
**page | Any | no | Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor. |
Returns: Any. Decoded JSON answer of the operation "List the delegations".
Raises: the typed errors of the transport (Errors).
DelegationsClient.restrict
restrict(delegation_id: str, delegate: str, scopes: list[str] | None = None, audience: str | None = None, resources: list[str] | None = None, purpose: str | None = None, ttl_seconds: int | None = None, expires_at: str | None = None, max_depth: int | None = None, redelegation_allowed: bool | None = None, data_classification_max: str | None = None, **extra: Any) -> Any
Restrict a delegation for a sub-delegate. Creates a child delegation, always covered by its parent: a sub-agent never gets wider rights. Allowed to the root or creator of the parent, an agent, a tenant_admin or a security_officer (403 forbidden).
Route: /v1/delegations/{delegation_id}/restrict (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
delegation_id | str | yes | Identifier (UUID) of the parent delegation. | |
delegate | str | yes | Sub-delegate: agent:<name>, app:<id>, service:<name> or subagent:<name>. | |
scopes | list[str] | None | None | no | Narrower scopes, at most 100, covered by the parent ones. |
audience | str | None | None | no | Narrower audiences, at most 20. |
resources | list[str] | None | None | no | Narrower resource restrictions, at most 100. |
purpose | str | None | None | no | Purpose of the child delegation, at most 2000 characters. |
ttl_seconds | int | None | None | no | Lifetime in seconds, at least 60, never beyond the parent expiry. |
expires_at | str | None | None | no | Expiry date and time (ISO 8601), never beyond the parent expiry. |
max_depth | int | None | None | no | Maximum depth of the chain under this branch, 0 to 10: at least the depth of the child, at most the parent max_depth (default: the parent value). |
redelegation_allowed | bool | None | None | no | Whether the sub-delegate may restrict again. |
data_classification_max | str | None | None | no | Lower or equal classification ceiling: public, internal, confidential, restricted or secret. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Restrict a delegation for a sub-delegate".
Raises: the typed errors of the transport (Errors).
DelegationsClient.revoke
revoke(delegation_id: str, reason: str | None = None) -> Any
Revoke a delegation. Revokes the delegation and every descendant; their execution contexts are revoked with them, effective at the next action. Allowed to its root, creator or the person acted for, and to tenant_admin and security_officer (403 forbidden). Writes the audit event delegation.revoke.
Route: /v1/delegations/{delegation_id}/revoke (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
delegation_id | str | yes | Identifier (UUID) of the delegation. | |
reason | str | None | None | no | Why the action is taken. Written to the audit trail with the actor and the time. |
Returns: Any. Decoded JSON answer of the operation "Revoke a delegation".
Raises: the typed errors of the transport (Errors).
DelegationsClient.revoke_principal
revoke_principal(principal_id: str, reason: str | None = None) -> Any
Revoke every delegation of a principal. Revokes every active delegation rooted at a principal or acting for it, with their descendants and execution contexts, for example at user offboarding or after an account compromise. Needs tenant_admin or security_officer. Writes the audit event delegation.revoke_principal.
Route: /v1/delegations/revoke-principal (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
principal_id | str | yes | Principal whose delegations are revoked, for example a user subject, 1 to 300 characters. | |
reason | str | None | None | no | Why, at most 2000 characters (empty by default). Written to the audit trail. |
Returns: Any. Decoded JSON answer of the operation "Revoke every delegation of a principal".
Raises: the typed errors of the transport (Errors).
DelegationsClient.verify
verify(delegation_id: str, action: str, scope: str | None = None, resource: str | None = None, relation: str | None = None, audience: str | None = None, data_classification: str | None = None, run_id: str | None = None) -> Any
Authorize an action under a delegation. Computes the effective permission of an action: user AND agent AND delegation AND resource restriction AND relationship (OpenFGA or the builtin tuples) AND policy (OPA or builtin). Give delegation_id, or run_id to use the delegation of a run (400 invalid_request without either; 403 delegation_required for a run without delegation).
Route: /v1/delegations/authorize (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
delegation_id | str | yes | Delegation to check. Give it or run_id. | |
action | str | yes | Action, dotted lowercase name such as tool.call or model.invoke, 3 to 200 characters. | |
scope | str | None | None | no | Scope the action needs, at most 200 characters. |
resource | str | None | None | no | Resource acted on, <type>:<id> such as tool:crm.search, at most 300 characters. |
relation | str | None | None | no | ReBAC relation checked on the resource, for example viewer. |
audience | str | None | None | no | Service that will receive the call, at most 200 characters. |
data_classification | str | None | None | no | Classification of the data handled: public, internal, confidential, restricted or secret. |
run_id | str | None | None | no | Run whose delegation is checked, instead of delegation_id. |
Returns: Any. Decoded JSON answer of the operation "Authorize an action under a delegation".
Raises: the typed errors of the transport (Errors).
Class MandatesClient
/v1/mandates: standing mandates of autonomous agents (scheduled work).
Resource
MandatesClient.create
create(agent: str, purpose: str, service_identity_id: str, scopes: list[str] | None = None, audience: str | None = None, resources: list[str] | None = None, schedule_id: str | None = None, ttl_days: int | None = None, max_depth: int | None = None, data_classification_max: str | None = None, **extra: Any) -> Any
Request a mandate for an agent. Requests a mandate so that an agent (optionally one of its schedules) runs autonomously under a service identity. Needs tenant_admin, developer or security_officer.
Route: /v1/mandates (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
agent | str | yes | Name of the agent, 1 to 200 characters. | |
purpose | str | yes | Purpose of the mandate, 3 to 2000 characters, shown to the approvers. | |
service_identity_id | str | yes | Service identity the runs act as; it must be active. | |
scopes | list[str] | None | None | no | Scopes of the mandate, at most 100, covered by those of the service identity. |
audience | str | None | None | no | Audiences, at most 20 patterns. Default eai-control-plane. |
resources | list[str] | None | None | no | Resource restrictions, at most 100 patterns. Default *. |
schedule_id | str | None | None | no | Single schedule of the agent covered by the mandate; null for every schedule of the agent. |
ttl_days | int | None | None | no | Lifetime in days, 1 to the platform maximum (365 by default); default 30. |
max_depth | int | None | None | no | Sub-delegation depth allowed, 0 to 10 (default 0). |
data_classification_max | str | None | None | no | Classification ceiling: public, internal, confidential, restricted or secret. Default: the clearance of the service identity. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Request a mandate for an agent".
Raises: the typed errors of the transport (Errors).
MandatesClient.get
get(mandate_id: str) -> Any
Get a mandate. Returns one mandate: agent, schedule, service identity, scopes, audience, resources, classification ceiling, depth, purpose, status, approval and expiry. Open to any member of the tenant. Answers 404 mandate_not_found.
Route: /v1/mandates/{mandate_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
mandate_id | str | yes | Identifier (UUID) of the mandate. |
Returns: Any. Decoded JSON answer of the operation "Get a mandate".
Raises: the typed errors of the transport (Errors).
MandatesClient.list
list(agent: str | None = None, limit: int | None = None) -> Any
List the mandates. Lists the mandates of the tenant, newest first, optionally for one agent, with their effective status (pending, approved, rejected, revoked or expired). Open to any member of the tenant.
Route: /v1/mandates (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
agent | str | None | None | no | Only the mandates of this agent (name). |
limit | int | None | None | no | Maximum number of mandates (default 50, maximum 500). |
Returns: Any. Decoded JSON answer of the operation "List the mandates".
Raises: the typed errors of the transport (Errors).
MandatesClient.revoke
revoke(mandate_id: str, reason: str | None = None) -> Any
Revoke a mandate. Revokes the mandate and the delegations rooted at it: the next scheduled run of the agent is refused (mandate_required). Allowed to the requester, a tenant_admin or a security_officer (403 forbidden). A revoked or rejected mandate answers 409 mandate_closed. Writes the audit event mandate.revoke.
Route: /v1/mandates/{mandate_id}/revoke (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
mandate_id | str | yes | Identifier (UUID) of the mandate. | |
reason | str | None | None | no | Why the action is taken. Written to the audit trail with the actor and the time. |
Returns: Any. Decoded JSON answer of the operation "Revoke a mandate".
Raises: the typed errors of the transport (Errors).
Class BreakGlassClient
/v1/break-glass: audited emergency grants with a short lifetime.
Resource
BreakGlassClient.context
context(grant_id: str, audience: str | None = None, ttl_seconds: int | None = None) -> Any
Get an execution context for a break glass grant. Returns a signed ExecutionContext carrying the active elevation, whose lifetime never exceeds the grant expiry. Only the beneficiary may ask (403 forbidden); the grant must be active (409 break_glass_not_active); each audience must be known (400 context_wrong_audience). Downstream services verify it like any execution context.
Route: /v1/break-glass/{grant_id}/context (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
grant_id | str | yes | Identifier (UUID) of the break glass grant. | |
audience | str | None | None | no | Services the execution context is meant for (1 to 10 known audiences); default the server choice. |
ttl_seconds | int | None | None | no | Lifetime in seconds. Once it has elapsed, the item expires and is no longer accepted. |
Returns: Any. Decoded JSON answer of the operation "Get an execution context for a break glass grant".
Raises: the typed errors of the transport (Errors).
BreakGlassClient.create
create(reason: str, duration_seconds: int, roles: list[str] | None = None, scopes: list[str] | None = None, beneficiary: str | None = None, incident_ref: str | None = None, **extra: Any) -> Any
Request a break glass elevation. Requests an exceptional, time bound elevation for the beneficiary (the caller by default). Open to any member of the tenant.
Route: /v1/break-glass (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
reason | str | yes | Justification, 10 to 4000 characters, shown to the approvers. | |
duration_seconds | int | yes | Duration of the elevation once approved, from 60 seconds to the platform maximum (3600 by default). | |
roles | list[str] | None | None | no | Tenant roles granted, at most 8, never platform_admin. Roles or scopes are required. |
scopes | list[str] | None | None | no | Scopes granted, at most 100 patterns. |
beneficiary | str | None | None | no | Subject who receives the elevation. Default: the caller. |
incident_ref | str | None | None | no | Reference of the incident that justifies the request, optional. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Request a break glass elevation".
Raises: the typed errors of the transport (Errors).
BreakGlassClient.get
get(grant_id: str) -> Any
Get a break glass grant. Returns one grant: requester, beneficiary, roles, scopes, reason, incident, duration, status, approval and dates. Visible to its requester and beneficiary and to tenant_admin, security_officer and auditor; anyone else gets 404 break_glass_not_found.
Route: /v1/break-glass/{grant_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
grant_id | str | yes | Identifier (UUID) of the break glass grant. |
Returns: Any. Decoded JSON answer of the operation "Get a break glass grant".
Raises: the typed errors of the transport (Errors).
BreakGlassClient.list
list(status: str | None = None, limit: int | None = None) -> Any
List the break glass grants. Lists break glass grants, newest first: all of them for tenant_admin, security_officer and auditor, otherwise those the caller requested or benefits from. Active grants past their expiry are marked expired (audited once). An unknown status answers 400.
Route: /v1/break-glass (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
status | str | None | None | no | Only pending, active, expired, rejected or revoked grants. |
limit | int | None | None | no | Maximum number of grants (default 50, maximum 500). |
Returns: Any. Decoded JSON answer of the operation "List the break glass grants".
Raises: the typed errors of the transport (Errors).
BreakGlassClient.revoke
revoke(grant_id: str, reason: str | None = None) -> Any
Revoke a break glass grant. Ends a pending or active grant and revokes the delegations created under it. Allowed to the requester, a tenant_admin or a security_officer (403 forbidden). A grant already closed answers 409 break_glass_closed. Writes the audit event break_glass.revoke.
Route: /v1/break-glass/{grant_id}/revoke (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
grant_id | str | yes | Identifier (UUID) of the break glass grant. | |
reason | str | None | None | no | Why the action is taken. Written to the audit trail with the actor and the time. |
Returns: Any. Decoded JSON answer of the operation "Revoke a break glass grant".
Raises: the typed errors of the transport (Errors).