resources/trust.ts

Source: sdks/typescript/packages/sdk/src/resources/trust.ts. Back to the TypeScript SDK reference index.

note

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 LicenseResource

License entitlement in force for the installation (contract license-entitlement).

Resource

LicenseResource.activate

activate(body: { token: string }, opts?: CallOptions)

Activate a licence. Verifies a signed licence locally and stores it. Requires the role platform_admin and the policy decision license.activate.

Route: /v1/license/activations (POST).

Name	Type	Default	Required	Description
body	{ token: string }		yes	The signed licence received from the publisher.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

LicenseResource.get

get(opts?: CallOptions)

Read the licence state. Non sensitive licence status of the installation: state, edition, product, term, validity and grace dates, days remaining, whether a renewal is scheduled, the actions restricted now, the capabilities a licence never restricts, and the banner the portal shows (level none, info, warning or critical, with an English and French message). No customer identifier, support reference or token is returned. Any authenticated principal may call it, subject to the policy decision license.read (403 policy_denied).

Route: /v1/license (GET).

Name	Type	Default	Required	Description
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

LicenseResource.history

history(params?: ListParams, opts?: CallOptions)

List the licence history. Licence history of the installation, newest event first: activations, rejected activations, actions refused after grace and expiry notices. The answer also gives the installation identity (installation id, installation group and when and by whom it was bound), every stored licence with its customer id, support reference and environments, and the support contracts. Requires the role platform_admin (403 forbidden) and the policy decision license.history.read. A malformed cursor answers 400 invalid_cursor.

Route: /v1/license/history (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface DelegationRestrict

Body of DelegationsResource.create and restrict: the delegate and the limits of the delegation.

Fields:

Name	Type	Required	Description
delegate	string	yes	Principal that receives the delegation.
audience	string	no	Audience the delegation is valid for.
data_classification_max	string	no	Highest data classification the delegate may reach.
expires_at	string	no	Date and time (ISO 8601, UTC) after which the item is no longer valid.
max_depth	number	no	Maximum length of the delegation chain.
purpose	string	no	Use of the target. Default backup.
redelegation_allowed	boolean	no	Whether the delegate may delegate again.
resources	string[]	no	Resources the delegation covers.
scopes	string[]	no	Scopes requested; must include openid. Default openid, profile, email.
ttl_seconds	number	no	Lifetime in seconds. Once it has elapsed, the item expires and is no longer accepted.

Interface DelegationAuthorize

Body of DelegationsResource.authorize (POST /v1/delegations/authorize): the action to decide under a delegation.

Fields:

Name	Type	Required	Description
action	string	yes	Action to authorize.
audience	string	no	Audience the action is meant for.
data_classification	string	no	Classification of the data the action touches.
delegation_id	string	no	Delegation to check; verify sets it from its argument.
relation	string	no	Relation checked on the resource.
resource	string	no	Resource the action targets.
run_id	string	no	Run the action belongs to.
scope	string	no	What is backed up (clusters, services, data sets), as an object.

Class DelegationsResource

Delegation chains: a principal hands a restricted subset of its rights to an agent.

Resource

DelegationsResource.authorize

authorize(body: DelegationAuthorize, opts?: CallOptions)

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
body	DelegationAuthorize		yes	Action, delegation or run, and the scope, resource, relation, audience and classification to check.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.create

create(body: DelegationRestrict & { session_id?: string }, opts?: CallOptions)

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
body	DelegationRestrict & { session_id?: string }		yes	Delegate, rights, limits and expiry of the delegation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the delegation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.iterate

iterate(params?: ListParams & { root_principal_id?: string; status?: string }, opts?: CallOptions)

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
params	ListParams & { root_principal_id?: string; status?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.list

list(params?: ListParams & { root_principal_id?: string; status?: string }, opts?: CallOptions)

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
params	ListParams & { root_principal_id?: string; status?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.restrict

restrict(id: string, body: DelegationRestrict, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the parent delegation.
body	DelegationRestrict		yes	Sub-delegate and narrower rights.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.revoke

revoke(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the delegation.
body	{ reason?: string }	{}	no	Optional reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.revokePrincipal

revokePrincipal(body: { principal_id: string; reason?: string }, opts?: CallOptions)

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
body	{ principal_id: string; reason?: string }		yes	Principal and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DelegationsResource.verify

verify(delegationId: string, body: Omit<DelegationAuthorize, "delegation_id">, opts?: CallOptions)

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
delegationId	string		yes	Delegation to check. Give it or run_id.
body	Omit<DelegationAuthorize, "delegation_id">		yes	Action, delegation or run, and the scope, resource, relation, audience and classification to check.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface MandateCreate

Body of MandatesResource.create (POST /v1/mandates): the standing authority asked for an autonomous agent.

Fields:

Name	Type	Required	Description
agent	string	yes	Agent that receives the mandate.
purpose	string	yes	Use of the target. Default backup.
service_identity_id	string	yes	Service identity the runs act as; it must be active.
audience	string	no	Audience the mandate is valid for.
data_classification_max	string	no	Highest data classification the agent may reach.
max_depth	number	no	Maximum length of the delegation chain under the mandate.
resources	string[]	no	Resources the mandate covers.
schedule_id	string	no	Single schedule of the agent covered by the mandate; null for every schedule of the agent.
scopes	string[]	no	Scopes requested; must include openid. Default openid, profile, email.
ttl_days	number	no	Lifetime of the mandate in days.

Class MandatesResource

Mandates: standing authority of an autonomous agent, granted through an approval.

Resource

MandatesResource.create

create(body: MandateCreate, opts?: CallOptions)

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
body	MandateCreate		yes	Agent, service identity, schedule, rights, purpose and lifetime of the mandate.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MandatesResource.decide

decide(approvalId: string, body: { decision: "approve" | "reject"; comment?: string }, opts?: CallOptions)

Approve or reject a request. Records the decision of the caller on a pending request.

Route: /v1/approvals/{approval_id}/decide (POST).

Name	Type	Default	Required	Description
approvalId	string		yes	Identifier (UUID) of the approval request.
body	{ decision: "approve" | "reject"; comment?: string }		yes	Decision and optional comment.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MandatesResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the mandate.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MandatesResource.list

list(params?: ListParams & { agent?: string }, opts?: CallOptions)

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
params	ListParams & { agent?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MandatesResource.revoke

revoke(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the mandate.
body	{ reason?: string }	{}	no	Optional reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface BreakGlassRequest

Body of BreakGlassResource.request (POST /v1/break-glass): a time boxed emergency access.

Fields:

Name	Type	Required	Description
reason	string	yes	Why the action is taken. Written to the audit trail with the actor and the time.
duration_seconds	number	yes	Duration of the emergency access in seconds.
beneficiary	string	no	Subject who receives the elevation. Default: the caller.
incident_ref	string	no	Reference of the incident that justifies the request, optional.
roles	string[]	no	Roles granted during the emergency access.
scopes	string[]	no	Scopes requested; must include openid. Default openid, profile, email.

Class BreakGlassResource

Break-glass: time boxed emergency access, audited and revocable.

Resource

BreakGlassResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the break glass grant.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

BreakGlassResource.issueContext

issueContext(id: string, body: { audience?: string; ttl_seconds?: number } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the break glass grant.
body	{ audience?: string; ttl_seconds?: number }	{}	no	Optional audiences and lifetime of the context.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

BreakGlassResource.list

list(params?: ListParams & { status?: string }, opts?: CallOptions)

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
params	ListParams & { status?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

BreakGlassResource.request

request(body: BreakGlassRequest, opts?: CallOptions)

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
body	BreakGlassRequest		yes	Roles, scopes, reason, duration, beneficiary and incident reference.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

BreakGlassResource.revoke

revoke(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the break glass grant.
body	{ reason?: string }	{}	no	Optional reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Type alias ApplicationKind

Kind of governed application: agent_app, assistant, workflow or external_agent.

Definition: "agent_app" \| "assistant" \| "workflow" \| "external_agent".

Interface ApplicationCreate

Body of ApplicationsResource.create (POST /v1/applications): a governed application and what it may use.

Fields:

Name	Type	Required	Description
name	string	yes	Name of the application.
kind	ApplicationKind	yes	Kind of application: agent_app, assistant, workflow or external_agent.
origin	"internal" | "third_party"	no	internal (default) or third_party; forced to third_party for an external_agent.
risk_level	"low" | "medium" | "high"	no	Risk level: low, medium or high.
owner	string	no	Owner of the application.
project	string	no	Identifier of the project the results are restricted to.
environments	string[]	no	Environments the application is deployed to.
agents	string[]	no	Agents used by the application.
models	string[]	no	Models used by the application.
tools	string[]	no	Tools its external agents may invoke (names or patterns such as crm.*).
mcp_servers	string[]	no	MCP servers its external agents may call (names or patterns).
plugins	string[]	no	Plugins granted to the application (names or patterns).

Class ApplicationsResource

Governed applications and third party agents.

Resource

ApplicationsResource.activateDeployment

activateDeployment(appId: string, deploymentId: string, opts?: CallOptions)

Activate an approved deployment. Activates the deployment once its approval is approved (separation of duties is enforced by the approvals domain; a missing approval is audited as a denial): the previous active deployment of the environment is retired and the application becomes active. 409 application_suspended; 404 application_deployment_not_found. Needs tenant_admin, developer or application_owner. Audited as application.deployment.activate with the approver.

Route: /v1/applications/{app_id}/deployments/{deployment_id}/activate (POST).

Name	Type	Default	Required	Description
appId	string		yes	Identifier (UUID) or name of the application.
deploymentId	string		yes	Identifier (UUID) of the deployment.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.create

create(body: ApplicationCreate, opts?: CallOptions)

Register an application. Creates the application (201). An external_agent is always of origin third_party. Owner defaults to the caller, project to the X-Project header. A name already used answers 409 conflict. Needs tenant_admin, developer or application_owner. Audited as application.create.

Route: /v1/applications (POST).

Name	Type	Default	Required	Description
body	ApplicationCreate		yes	Name, kind, origin, owner, project, environments, risk level and granted resources.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.createDeployment

createDeployment(appId: string, body: { version: string; environment: string; reason?: string }, opts?: CallOptions)

Request a deployment. Records a deployment of a version in one environment of the application and opens an application_deployment approval for tenant_admin or security_officer (201, the deployment carries approval_id). The environment must be declared by the application (400 invalid_request); the same version in the same environment answers 409 conflict; a suspended or retired application answers 409 application_suspended. Needs tenant_admin, developer or application_owner. Audited as application.deployment.create.

Route: /v1/applications/{app_id}/deployments (POST).

Name	Type	Default	Required	Description
appId	string		yes	Identifier (UUID) or name of the application.
body	{ version: string; environment: string; reason?: string }		yes	Version, environment and reason shown to the approvers.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.createExternalAgent

createExternalAgent(appId: string, body: { name: string; scopes?: string[] }, opts?: CallOptions)

Register a third party agent identity. Creates an API key with the role agent, bound to the application and its project, with the scopes tools:invoke, models:invoke plus the requested ones (201). The key is in api_key and is shown only once. Needs tenant_admin. Audited as application.external_agent.register.

Route: /v1/applications/{app_id}/external-agents (POST).

Name	Type	Default	Required	Description
appId	string		yes	Identifier (UUID) or name of the application.
body	{ name: string; scopes?: string[] }		yes	Name of the identity and extra scopes.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.developerKit

developerKit(query: { application_id?: string; agent_id?: string; project?: string }, opts?: CallOptions)

Get the developer kit. Developer kit of an application, an agent or a project: values, states and actions, never a secret. Give exactly one of application_id, agent_id or project (400 invalid_request otherwise). The answer holds the subject (with the models, tools, MCP servers, knowledge bases and evaluation suites it uses), the nine rows, the env entries of an environment file (the API key is only a placeholder marked secret), a summary of ready rows and the next_steps (create a key, run the tests, run the red team). An unknown application or agent, or a project without application, answers 404 not_found. Requires a tenant principal (403 tenant_required) with developer, application_owner or tenant_admin (403 forbidden).

Route: /v1/developer/kit (GET).

Name	Type	Default	Required	Description
query	{ application_id?: string; agent_id?: string; project?: string }		yes	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.get

get(appId: string, opts?: CallOptions)

Get an application. Returns the application and its deployments, oldest first. 404 application_not_found.

Route: /v1/applications/{app_id} (GET).

Name	Type	Default	Required	Description
appId	string		yes	Identifier (UUID) or name of the application.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.list

list(opts?: CallOptions)

List the applications. Applications of the tenant in name order, with kind, origin, status, environments and granted resources. One page only.

Route: /v1/applications (GET).

Name	Type	Default	Required	Description
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ApplicationsResource.setStatus

setStatus(appId: string, body: { status: "suspended" | "retired"; reason: string }, opts?: CallOptions)

Suspend or retire an application. Sets the application to suspended or retired and its active deployments too; every gateway call of its external agents is refused from then on. Needs tenant_admin or security_officer. Audited as application.suspended or application.retired.

Route: /v1/applications/{app_id}/status (POST).

Name	Type	Default	Required	Description
appId	string		yes	Identifier (UUID) or name of the application.
body	{ status: "suspended" | "retired"; reason: string }		yes	Target status and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).