resources/identity.ts

Source: sdks/typescript/packages/sdk/src/resources/identity.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 MetaResource

System. Technical endpoints of the Control Plane: liveness and readiness probes, description of the instance, identity of the caller, the catalog of platform bricks and the product roadmap.

Resource

MetaResource.get

get(opts?: CallOptions)

Describe the Control Plane instance. Name, version and API version of the instance, supported locales and default locale, loaded domains, and the features enabled by the configuration: OIDC, API key, SPIFFE and development authentication, OpenBao, OpenFGA, OPA and LiteLLM (true when their address is set). No authentication required.

Route: /v1/meta (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).

MetaResource.health

health(opts?: CallOptions)

Check that the process is alive. Liveness probe: always answers 200 with status: ok and the version of the Control Plane while the process serves requests. It checks no dependency. No authentication, no rate limit.

Route: /healthz (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).

MetaResource.metrics

metrics(opts?: CallOptions)

GET /metrics: Prometheus text format (not part of the OpenAPI schema).

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

MetaResource.ready

ready(opts?: CallOptions)

Check that the instance is ready. Readiness probe: checks that the database answers and that the schema migrations were applied. Answers 200 ready when every check passes, else 503 not_ready, with the result of each check and a message in the language of the request. The Redis cache state is reported but never makes the instance not ready. No authentication, no rate limit.

Route: /readyz (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).

Interface Me

Answer of GET /v1/me: principal, tenant, roles and scopes of the caller.

Doc

Fields:

Name	Type	Required	Description
principal	Doc	no	Unix account of the certificate. Default navin-breakglass.
tenant	Doc	no	Tenant slug.
roles	string[]	no	Roles of the caller.
scopes	string[]	no	Scopes requested; must include openid. Default openid, profile, email.

Class MeResource

The signed in caller: /v1/me, whoami, local account login, password change and logout.

Resource

MeResource.changePassword

changePassword(body: { current_password: string; new_password: string }, opts?: CallOptions)

Change the password. Changes the password of the signed in local account. Only for a portal session (403 password_session_required).

Route: /v1/auth/password (POST).

Name	Type	Default	Required	Description
body	{ current_password: string; new_password: string }		yes	Current and new password.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MeResource.get

get(opts?: CallOptions)

Read the current principal. Who the caller is: principal id, kind, tenant, clearance, project, environment, authentication method and display name, with its roles and scopes. When the principal belongs to a tenant, the tenant (id, slug, name, status, data residency) is returned too. Requires authentication (401 otherwise).

Route: /v1/me (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).

MeResource.login

login(body: { username: string; password: string }, opts?: CallOptions)

Sign in with a login and a password. Opens a portal session for a local account. No credential is needed. The login is compared without case.

Route: /v1/auth/login (POST).

Name	Type	Default	Required	Description
body	{ username: string; password: string }		yes	Login and password of the local account.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MeResource.logout

logout(opts?: CallOptions)

Sign out. Revokes the current portal session: its token is refused from now on (401 session_revoked). Only for a portal session (403 password_session_required with another credential). Writes the audit event auth.logout. Answers 204.

Route: /v1/auth/logout (POST).

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

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

MeResource.whoami

whoami(opts?: CallOptions)

Show the calling identity. Returns the identity the platform resolved for this request, whatever the credential (OIDC token, portal session, API key, SPIFFE): id, kind (user, service, agent, system), tenant_id, tenant_slug, roles, scopes, clearance, auth_method and display. Read only, open to any authenticated caller, also while a local account must still change its password. Use it to check a new token or key.

Route: /v1/identity/whoami (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).

Class CatalogResource

System. Technical endpoints of the Control Plane: liveness and readiness probes, description of the instance, identity of the caller, the catalog of platform bricks and the product roadmap.

Resource

CatalogResource.getBrick

getBrick(id: string, opts?: CallOptions)

Get one platform brick. One brick of the catalog, matched on its id without regard to case. Answers 404 not_found when no brick has this id. No authentication required.

Route: /v1/catalog/bricks/{brick_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier of the brick in the catalog, case insensitive.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

CatalogResource.listBricks

listBricks(opts?: CallOptions)

List the platform bricks. Catalog of the platform bricks read from bricks.yaml of the catalog folder, in one page (next_cursor is always null). The file is loaded as safe YAML (no anchors or aliases, 2 MB at most). No authentication required.

Route: /v1/catalog/bricks (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).

Class RoadmapResource

System. Technical endpoints of the Control Plane: liveness and readiness probes, description of the instance, identity of the caller, the catalog of platform bricks and the product roadmap.

Resource

RoadmapResource.get

get(opts?: CallOptions)

Read the product roadmap. Roadmap read from roadmap.yaml of the catalog folder, always with a phases list (empty when the file is missing). Loaded as safe YAML. No authentication required.

Route: /v1/roadmap (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).

Class OperationsResource

Long operations (architecture B6.3): follow the Operation-Id returned by a long creation.

Resource

OperationsResource.get

get(operationId: string, opts?: CallOptions)

Follow a long operation. The operation (kind, state pending or accepted, method, path, HTTP status, idempotency key, tracked resource, creator and dates), its accepted answer and the live state of the tracked resource. The resource is read with the caller's credentials through the resource route, so the resource authorization applies: when that read fails, result stays null and result_error.http_status gives the status. status is pending while the request runs, then the status or state of the resource. Requires a tenant principal (403 tenant_required); an operation created by someone else answers 404 not_found unless the caller holds tenant_admin, platform_admin, auditor or security_officer.

Route: /v1/operations/{operation_id} (GET).

Name	Type	Default	Required	Description
operationId	string		yes	Identifier of the operation, as returned in the Operation-Id header.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class ContractsResource

Contracts and manifests. Published JSON Schemas (contracts) of the platform documents, and declarative manifests that create or update objects from a document, in the spirit of infrastructure as code.

Resource

ContractsResource.get

get(name: ContractName | string, opts?: CallOptions)

Get a contract. Returns the JSON Schema of the contract as published. Open to any authenticated caller. An unknown name answers 404 unknown_contract.

Route: /v1/contracts/{name} (GET).

Name	Type	Default	Required	Description
name	ContractName | string		yes	Name of the contract, for example agent-manifest.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ContractsResource.list

list(opts?: CallOptions)

List the contracts. Lists the published contracts with their name, title, kind, type, file, schema id and description. Open to any authenticated caller. next_cursor is always null.

Route: /v1/contracts (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).

ContractsResource.validate

validate(name: ContractName | string, document: unknown, opts?: CallOptions)

Validate a document against a contract. Validates the body against the contract, formats included, without storing anything. The answer gives contract, valid and errors, each with the JSON path of the faulty value and a message. Open to any authenticated caller. An unknown contract answers 404 unknown_contract.

Route: /v1/contracts/{name}/validate (POST).

Name	Type	Default	Required	Description
name	ContractName | string		yes	Name of the contract, for example agent-manifest.
document	unknown		yes	Document to validate against the contract.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ContractsResource.validateLocal

validateLocal(name: ContractName | string, document: unknown): ContractValidationResult

Client side validation with the bundled schemas (no network call).

Name	Type	Default	Required	Description
name	ContractName | string		yes	Name of the contract, for example agent-manifest.
document	unknown		yes	Document to validate against the contract.

Returns: ContractValidationResult. Validation result with the errors found.

Interface ApplyResult

Answer of ManifestsResource.apply: kind, name, version and status of the applied manifest.

Doc

Fields:

Name	Type	Required	Description
kind	ManifestKind	yes	Kind of the manifest.
name	string	yes	Name of the manifest.
version	string	yes	Version of the manifest.
status	string	yes	Result of the apply.

Class ManifestsResource

Contracts and manifests. Published JSON Schemas (contracts) of the platform documents, and declarative manifests that create or update objects from a document, in the spirit of infrastructure as code.

Resource

ManifestsResource.apply

async apply(manifest: Manifest | Doc, opts?: CallOptions & { validate?: boolean }): Promise<ApplyResult>

Apply a manifest. Creates or updates the object described by a manifest, in one transaction. Needs tenant_admin or developer.

Route: /v1/manifests/apply (POST).

Name	Type	Default	Required	Description
manifest	Manifest | Doc		yes	Manifest to apply; it is validated against the contract of its kind first unless validate is false.
opts	CallOptions & { validate?: boolean }		no	Per call options (query, idempotency key, traceparent, headers).

Returns: Promise<ApplyResult>. Decoded JSON answer of the operation "Apply a manifest".

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

Class TenantsResource

Tenancy. Tenants, their hierarchy, projects, environments and members.

Resource

TenantsResource.create

create(body: Doc, opts?: CallOptions)

Create a tenant. Creates a tenant and makes each subject of admins its tenant_admin. Needs platform_admin. A slug already used answers 409 conflict. Writes the audit event tenant.create in the chain of the new tenant.

Route: /v1/tenants (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Slug, name, residency, settings and first administrators of the tenant.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

TenantsResource.get

get(id: string, opts?: CallOptions)

Get a tenant. Returns one tenant: slug, name, status, data residency and settings. A tenant the caller may not see answers 404 not_found.

Route: /v1/tenants/{tenant_id} (GET).

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

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

TenantsResource.iterate

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

List the tenants. Lists the tenants the caller may see, ordered by slug, paginated: their own tenant for a tenant credential, every tenant for a platform administrator.

Route: /v1/tenants (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).

TenantsResource.list

list(params?: ListParams, opts?: CallOptions): Promise<Page<Doc>>

List the tenants. Lists the tenants the caller may see, ordered by slug, paginated: their own tenant for a tenant credential, every tenant for a platform administrator.

Route: /v1/tenants (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).

Returns: Promise<Page<Doc>>. Decoded JSON answer of the operation "List the tenants".

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

TenantsResource.update

update(id: string, body: Doc, opts?: CallOptions)

Update a tenant. Changes the name, data residency, settings or status of a tenant. Needs tenant_admin; changing status (active or suspended) needs a platform administrator (403 forbidden). A suspended tenant answers 403 tenant_suspended to every credential. Writes the audit event tenant.update.

Route: /v1/tenants/{tenant_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the tenant.
body	Doc		yes	Fields to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class ProjectsResource

Tenancy. Tenants, their hierarchy, projects, environments and members.

Resource

ProjectsResource.create

create(body: Doc, opts?: CallOptions)

Create a project. Creates a project in the tenant of the caller. Needs tenant_admin.

Route: /v1/projects (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Slug, name, settings, environments and attachment of the project.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ProjectsResource.createEnvironment

createEnvironment(id: string, body: Doc, opts?: CallOptions)

Create an environment. Adds an environment (dev, test, staging or prod) to the project. Needs tenant_admin and the relation editor on the project. An environment that already exists answers 409 conflict. Writes the audit event environment.create.

Route: /v1/projects/{project_id}/environments (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the project.
body	Doc		yes	Name and settings of the environment.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ProjectsResource.delete

delete(id: string, opts?: CallOptions)

Delete a project. Deletes the project and its environments. Needs tenant_admin and the relation owner on the project (403 relation_required). Objects that still reference the project may block the deletion (409 conflict). Writes the audit event project.delete. Answers 204.

Route: /v1/projects/{project_id} (DELETE).

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

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

ProjectsResource.get

get(id: string, opts?: CallOptions)

Get a project. Returns the project with its environments. Needs the relation viewer on the project (403 relation_required, audited). Answers 404 not_found for an unknown project.

Route: /v1/projects/{project_id} (GET).

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

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

ProjectsResource.iterate

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

List the projects. Lists the projects of the tenant ordered by slug, paginated, optionally filtered by organization or business unit. Open to any member of the tenant.

Route: /v1/projects (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).

ProjectsResource.list

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

List the projects. Lists the projects of the tenant ordered by slug, paginated, optionally filtered by organization or business unit. Open to any member of the tenant.

Route: /v1/projects (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).

ProjectsResource.listEnvironments

listEnvironments(id: string, opts?: CallOptions)

List the environments of a project. Lists the environments of the project, ordered by name. Needs the relation viewer on the project. Not paginated: next_cursor is always null.

Route: /v1/projects/{project_id}/environments (GET).

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

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

ProjectsResource.update

update(id: string, body: Doc, opts?: CallOptions)

Update a project. Changes the name, description, settings, metadata or attachment of a project. Sending organization_id or business_unit_id as null detaches the project. The unit must belong to the organization (422 invalid_hierarchy). Needs tenant_admin and the relation editor on the project. Send expected_version to detect a concurrent change (409 version_conflict). Writes the audit event project.update.

Route: /v1/projects/{project_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the project.
body	Doc		yes	Fields to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class OrganizationsResource

Tenant hierarchy (ADR-0156): organizations of the tenant. PATCH with expected_version is optimistic (409 version_conflict).

Resource

OrganizationsResource.create

create(body: { slug: string; name: string; description?: string; metadata?: Doc }, opts?: CallOptions)

Create an organization. Creates an organization in the tenant. Needs tenant_admin. A slug already used answers 409 conflict. Writes the audit event organization.create.

Route: /v1/organizations (POST).

Name	Type	Default	Required	Description
body	{ slug: string; name: string; description?: string; metadata?: Doc }		yes	Slug, name, description and metadata of the organization.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

OrganizationsResource.iterate

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

List the organizations. Lists the organizations of the tenant, paginated. Open to any member of the tenant.

Route: /v1/organizations (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).

OrganizationsResource.list

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

List the organizations. Lists the organizations of the tenant, paginated. Open to any member of the tenant.

Route: /v1/organizations (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).

OrganizationsResource.update

update(organizationId: string, body: Doc & { expected_version?: number }, opts?: CallOptions)

Update an organization. Changes the name, description, status (active or archived) or metadata of an organization. Needs tenant_admin. Send expected_version to detect a concurrent change (409 version_conflict). Writes the audit event organization.update.

Route: /v1/organizations/{organization_id} (PATCH).

Name	Type	Default	Required	Description
organizationId	string		yes	Identifier (UUID) of the organization.
body	Doc & { expected_version?: number }		yes	Fields to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class BusinessUnitsResource

Tenant hierarchy (ADR-0156): business units of an organization, optionally nested.

Resource

BusinessUnitsResource.create

create(body: { organization_id: string; parent_id?: string; slug: string; name: string; description?: string; metadata?: Doc }, opts?: CallOptions)

Create a business unit. Creates a business unit in an organization, optionally under a parent unit of the same organization (422 invalid_hierarchy otherwise). Needs tenant_admin. A slug already used answers 409 conflict. Writes the audit event business_unit.create.

Route: /v1/business-units (POST).

Name	Type	Default	Required	Description
body	{ organization_id: string; parent_id?: string; slug: string; name: string; description?: string; metadata?: Doc }		yes	Organization, parent, slug, name and description of the unit.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

BusinessUnitsResource.list

list(params?: ListParams & { organization_id?: string; parent_id?: string }, opts?: CallOptions)

List the business units. Lists the business units of the tenant, paginated, optionally filtered by organization or by parent unit. Open to any member of the tenant.

Route: /v1/business-units (GET).

Name	Type	Default	Required	Description
params	ListParams & { organization_id?: string; parent_id?: 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).

BusinessUnitsResource.update

update(businessUnitId: string, body: Doc & { expected_version?: number }, opts?: CallOptions)

Update a business unit. Changes the name, description, status (active or archived) or metadata of a business unit. Its organization and parent cannot change. Needs tenant_admin. Send expected_version to detect a concurrent change (409 version_conflict). Writes the audit event business_unit.update.

Route: /v1/business-units/{business_unit_id} (PATCH).

Name	Type	Default	Required	Description
businessUnitId	string		yes	Identifier (UUID) of the business unit.
body	Doc & { expected_version?: number }		yes	Fields to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class MembersResource

Members of the tenant (/v1/members), quota profiles and directory group mappings (/v1/identity).

Resource

MembersResource.create

create(body: Doc, opts?: CallOptions)

Add a member. Gives a user (OIDC subject) a role and a clearance in the tenant, or in one project with project_id. The user record is created when unknown; an existing membership for the same user and project is updated. Needs tenant_admin; granting platform_admin needs a platform administrator (403 forbidden). Writes the audit event member.assign.

Route: /v1/members (POST).

Name	Type	Default	Required	Description
body	Doc		yes	User, role, clearance and optional project of the membership.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.createGroupMapping

createGroupMapping(body: { group: string } & Doc, opts?: CallOptions)

Create a group mapping. Maps a directory group to a project role and, optionally, a quota profile. Needs tenant_admin.

Route: /v1/identity/group-mappings (POST).

Name	Type	Default	Required	Description
body	{ group: string } & Doc		yes	Group, project, role and optional quota profile of the mapping.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.createQuotaProfile

createQuotaProfile(body: { name: string } & Doc, opts?: CallOptions)

Create a quota profile. Creates a reusable quota profile for group mappings. Needs tenant_admin. At least one of limit_cost and limit_tokens is required (422 validation_error). A name already used answers 409 conflict. Writes the audit event identity.quota_profile.create.

Route: /v1/identity/quota-profiles (POST).

Name	Type	Default	Required	Description
body	{ name: string } & Doc		yes	Name, period, enforcement and limits of the profile.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.delete

delete(id: string, opts?: CallOptions)

Remove a member. Removes the membership: the user loses the role it gave at the next request. Needs tenant_admin. Writes the audit event member.remove. Answers 204, or 404 not_found.

Route: /v1/members/{member_id} (DELETE).

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

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

MembersResource.deleteGroupMapping

deleteGroupMapping(id: string, opts?: CallOptions)

Delete a group mapping. Deletes the mapping and withdraws what it granted (project memberships and quotas recorded as granted by this mapping); memberships granted by hand stay. Needs tenant_admin. Writes the audit event identity.group_mapping.delete. Answers 204, or 404 not_found for an unknown mapping.

Route: /v1/identity/group-mappings/{mapping_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the group mapping.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.deleteQuotaProfile

deleteQuotaProfile(id: string, opts?: CallOptions)

Delete a quota profile. Deletes a quota profile. Needs tenant_admin. A profile still used by a group mapping cannot be deleted (409 conflict): detach it from the mappings first. Writes the audit event identity.quota_profile.delete. Answers 204, or 404 not_found.

Route: /v1/identity/quota-profiles/{profile_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the quota profile.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.getGroupMapping

getGroupMapping(id: string, opts?: CallOptions)

Get a group mapping. Returns one group mapping. Needs tenant_admin, security_officer or auditor. Answers 404 not_found for an unknown mapping.

Route: /v1/identity/group-mappings/{mapping_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the group mapping.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.iterate

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

List the members. Lists the memberships of the tenant, paginated: user subject, email, display name, role, clearance, project and creation date. Open to any member of the tenant.

Route: /v1/members (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).

MembersResource.list

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

List the members. Lists the memberships of the tenant, paginated: user subject, email, display name, role, clearance, project and creation date. Open to any member of the tenant.

Route: /v1/members (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).

MembersResource.listGroupMappings

listGroupMappings(opts?: CallOptions)

List the group mappings. Lists every directory group mapping of the tenant with its group, project, role and quota profile. Needs tenant_admin, security_officer or auditor (403 forbidden otherwise). Not paginated: next_cursor is always null.

Route: /v1/identity/group-mappings (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).

MembersResource.listQuotaProfiles

listQuotaProfiles(opts?: CallOptions)

List the quota profiles. Lists the quota profiles of the tenant (name, period, enforcement, cost and token limits, currency). Needs tenant_admin, security_officer or auditor.

Route: /v1/identity/quota-profiles (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).

MembersResource.update

update(id: string, body: Doc, opts?: CallOptions)

Update a member. Changes the role or the clearance of a membership. Needs tenant_admin; granting platform_admin needs a platform administrator (403 forbidden). Writes the audit event member.update. Answers 404 not_found for an unknown membership.

Route: /v1/members/{member_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the membership.
body	Doc		yes	New role and/or clearance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.updateGroupMapping

updateGroupMapping(id: string, body: Doc, opts?: CallOptions)

Update a group mapping. Changes the group, project, role or quota profile of a mapping; only the fields sent change. clear_quota_profile: true detaches the profile. The new values apply at the next sign in of each member. Needs tenant_admin. A change that would duplicate another mapping answers 409 conflict; an unknown project or profile answers 404. Writes the audit event identity.group_mapping.update.

Route: /v1/identity/group-mappings/{mapping_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the group mapping.
body	Doc		yes	Fields to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

MembersResource.updateQuotaProfile

updateQuotaProfile(id: string, body: Doc, opts?: CallOptions)

Update a quota profile. Updates the period, enforcement or limits of a profile, and the user quotas already created from it through group mappings, in the same transaction. Needs tenant_admin. Writes the audit event identity.quota_profile.update with the number of quotas updated. Answers 404 not_found for an unknown profile.

Route: /v1/identity/quota-profiles/{profile_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the quota profile.
body	Doc		yes	Fields to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class ApiKeysResource

Identity. Who calls the API and with which rights. This tag covers the caller identity (whoami), API keys for scripts and services, service identities (SPIFFE workloads) that a user may temporarily act as, and the directory group mappings that turn Keycloak groups into project memberships and quotas.

Resource

ApiKeysResource.create

create(body: { name: string; scopes?: string[]; expires_at?: string } & Doc, opts?: CallOptions)

Create an API key. Creates an API key for scripts and services. Needs tenant_admin or developer. The answer (201) carries the full secret in key, shown only once: store it in a secret store right away.

Route: /v1/api-keys (POST).

Name	Type	Default	Required	Description
body	{ name: string; scopes?: string[]; expires_at?: string } & Doc		yes	Name, rights, binding and expiry of the new key.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ApiKeysResource.delete

delete(id: string, opts?: CallOptions)

Revoke an API key. Revokes the key at once: every later request made with it answers 401 api_key_revoked. Revoking a key already revoked succeeds without change. Allowed to tenant_admin, security_officer and developer; a developer only revokes the keys they created, any other key answers 404 not_found. Writes the audit event api_key.revoke. Answers 204 without body.

Route: /v1/api-keys/{key_id} (DELETE).

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

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

ApiKeysResource.list

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

List the API keys. Lists the API keys of the tenant, paginated by limit and cursor, ordered by identifier. Each item gives the name, the public prefix, roles, scopes, clearance, project, environment, creator, expiry and revocation state; never the secret nor its hash. tenant_admin and security_officer see every key, a developer only the keys they created.

Route: /v1/api-keys (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).

ApiKeysResource.rotate

rotate(id: string, opts?: CallOptions)

Rotate an API key. Issues a replacement key with the same name, roles, scopes, clearance, project and environment, and retires the old one. The new secret is in key of the 201 answer, shown once.

Route: /v1/api-keys/{key_id}/rotate (POST).

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

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

Interface ServiceIdentityAssume

Body of POST /v1/service-identities/{identity_id}/assume (B9.3 identity.assumeService).

Fields:

Name	Type	Required	Description
purpose	string	yes	Why the caller acts as the service, 3 to 500 characters, signed into the context and audited.
audience	string[]	no	Downstream audiences allowed to verify the context (default: the authority audiences).
ttl_seconds	number	no	Lifetime of the context, 30 to 3600 seconds (default 900).
scopes	string[]	no	Requested scopes (default: the identity scopes); never more than the identity grants and the caller holds.

Interface AssumedServiceContext

Signed ExecutionContext returned by an assumption: not an API credential, verified downstream.

Fields:

Name	Type	Required	Description
token	string	yes	Access token of the Hub. Write only, sealed; null keeps the stored token.
context_id	string	yes	Id of the context, used to revoke it.
kid	string	yes	Id of the signing key.
alg	string	yes	Signature algorithm of the token.
issued_at	string	yes	Time the context was issued.
expires_at	string	yes	Date and time (ISO 8601, UTC) after which the item is no longer valid.
audience	string[]	yes	Downstream audiences allowed to verify the context.
digest	string	yes	SHA-256 of the evidence (commands, recording), at most 100 characters.
context	Doc	yes	Decoded content of the signed context.
service_identity	{ id: string; name: string; spiffe_id: string }	yes	Id, name and SPIFFE id of the assumed service identity.
effective	{ roles: string[]; scopes: string[]; clearance: string }	yes	Roles, scopes and clearance in force under the context.
assumed_by	string	yes	Principal that assumed the service identity.
on_behalf_of	string	yes	Principal the service acts for.
decision_id	string | null	yes	Id of the policy decision that allowed the assumption, or null.

Class ServiceIdentitiesResource

Identity. Who calls the API and with which rights. This tag covers the caller identity (whoami), API keys for scripts and services, service identities (SPIFFE workloads) that a user may temporarily act as, and the directory group mappings that turn Keycloak groups into project memberships and quotas.

Resource

ServiceIdentitiesResource.assume

async assume(identityId: string, body: ServiceIdentityAssume, opts?: CallOptions): Promise<AssumedServiceContext>

Assume a service identity. Returns a signed, short lived ExecutionContext whose subject is the service identity, for the caller. It is not an API credential: downstream services verify it (POST /v1/context/verify or the JWKS) and the caller revokes it with POST /v1/context/{context_id}/revoke.

Route: /v1/service-identities/{identity_id}/assume (POST).

Name	Type	Default	Required	Description
identityId	string		yes	Identifier (UUID) of the service identity.
body	ServiceIdentityAssume		yes	Purpose, audiences, lifetime and scopes of the requested context.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Returns: Promise<AssumedServiceContext>. A AssumedServiceContext: Signed ExecutionContext returned by an assumption: not an API credential, verified downstream.

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

ServiceIdentitiesResource.create

create(body: Doc, opts?: CallOptions)

Create a service identity. Registers a workload identity of the tenant with its SPIFFE ID, roles, scopes and clearance. Needs tenant_admin or security_officer; the roles and scopes granted follow the same rules as API keys (only what the caller holds). A SPIFFE ID already registered answers 409 conflict. Writes the audit event service_identity.create. Assuming the identity also needs the explicit relation can_assume (see the assume route).

Route: /v1/service-identities (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Name, SPIFFE ID and rights of the identity.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ServiceIdentitiesResource.delete

delete(id: string, opts?: CallOptions)

Delete a service identity. Deletes the service identity; it can no longer be assumed nor authenticate with its SPIFFE ID. Needs tenant_admin or security_officer. Writes the audit event service_identity.delete. Answers 204, or 404 not_found.

Route: /v1/service-identities/{identity_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the service identity.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ServiceIdentitiesResource.list

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

List the service identities. Lists the service identities of the tenant, ordered by name, with their SPIFFE ID, roles, scopes and clearance. Open to any member of the tenant. Not paginated: next_cursor is always null.

Route: /v1/service-identities (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 AuthzTuple

OpenFGA relation tuple: subject, relation and object.

Fields:

Name	Type	Required	Description
subject	string	yes	Subject of the relation.
relation	string	yes	Relation between the subject and the object.
object	string	yes	Object checked, <type>:<id>, for example project:42.

Class AuthzResource

OpenFGA checks and tuples (/v1/authz) and explained OPA decisions (/v1/policies/evaluate).

Resource

AuthzResource.check

async check(body: AuthzTuple & { contextual_tuples?: AuthzTuple[] }, opts?: CallOptions)

Check a relation. Tells whether subject holds relation on object, following inheritance. Up to 20 contextual_tuples are taken as true for this check only and never stored (an invalid one answers 422 validation_error). Open to any member of the tenant. The answer gives allowed, engine, subject, relation and object. Writes the audit event authz.check with the decision. When the engine cannot answer, the decision is a refusal, it is audited and the API answers 502 authz_backend_error.

Route: /v1/authz/check (POST).

Name	Type	Default	Required	Description
body	AuthzTuple & { contextual_tuples?: AuthzTuple[] }		yes	Subject, relation, object and optional contextual tuples.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AuthzResource.checkBatch

async checkBatch(checks: Array<AuthzTuple & { contextual_tuples?: AuthzTuple[] }>, opts?: CallOptions)

One POST /v1/authz/check per tuple, in order; allowed is true only when every check was confirmed allowed.

Name	Type	Default	Required	Description
checks	Array<AuthzTuple & { contextual_tuples?: AuthzTuple[] }>		yes	Tuples to check, each with optional contextual tuples; an empty list gives allowed false.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

AuthzResource.deleteTuples

deleteTuples(body: { tuples: AuthzTuple[] } | AuthzTuple, opts?: CallOptions)

Delete authorization tuples. Deletes one tuple ({subject, relation, object}) or up to 100 ({"tuples": [...]}). Needs tenant_admin or security_officer. Tuples that do not exist are ignored; the answer gives deleted (number removed) and engine. Writes the audit event authz.delete. 502 authz_backend_error when the engine cannot answer.

Route: /v1/authz/tuples (DELETE).

Name	Type	Default	Required	Description
body	{ tuples: AuthzTuple[] } | AuthzTuple		yes	One tuple, or an object tuples with 1 to 100 tuples.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AuthzResource.explain

async explain(body: { action: string; resource: Doc; context?: Doc; subject?: Doc }, opts?: CallOptions)

Evaluate a policy request. Returns the decision for a Policy Contract request. The body is a Policy Contract ({schema_version, request}) or just its request object (subject, action, resource, context); it is validated against the policy-contract contract (422 validation_error).

Route: /v1/policies/evaluate (POST).

Name	Type	Default	Required	Description
body	{ action: string; resource: Doc; context?: Doc; subject?: Doc }		yes	Policy Contract document, or its request object alone.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AuthzResource.listTuples

listTuples(query?: { subject?: string; object?: string }, opts?: CallOptions)

List authorization tuples. Lists the stored tuples of the tenant, ordered by object, relation and subject, at most 1000, optionally filtered by object and subject (exact match). Open to any member of the tenant. next_cursor is always null.

Route: /v1/authz/tuples (GET).

Name	Type	Default	Required	Description
query	{ subject?: string; object?: string }		no	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).

AuthzResource.writeTuples

writeTuples(body: { tuples: AuthzTuple[] } | AuthzTuple, opts?: CallOptions)

Write authorization tuples. Grants one tuple ({subject, relation, object}) or up to 100 ({"tuples": [...]}) in one transaction. Needs tenant_admin or security_officer. A wildcard subject (user:*) on a relation reserved to named subjects, such as can_assume, answers 422 authz_wildcard_not_allowed. The answer (201) gives written and engine. Writes the audit event authz.write. 502 authz_backend_error when the engine cannot answer.

Route: /v1/authz/tuples (POST).

Name	Type	Default	Required	Description
body	{ tuples: AuthzTuple[] } | AuthzTuple		yes	One tuple, or an object tuples with 1 to 100 tuples.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Type alias OPA_BUNDLE_STATUS_PATH

OPA status endpoint the Control Plane reads to report the bundle revision an engine runs (OPA API, not Control Plane).

Class PoliciesResource

Policies. Attribute based policies (ABAC) that decide every sensitive action of the platform, with the Policy Contract v1, the decision log, simulation, revisions and signed OPA bundles.

Resource

PoliciesResource.create

create(body: Doc, opts?: CallOptions)

Create a policy. Creates a policy of the tenant and appends its first revision. An opa policy needs rego (422 validation_error) and, unless OPA loads signed bundles, is pushed to OPA at once (503 policy_engine_unavailable when OPA cannot be reached). A name already used answers 409 conflict. Needs tenant_admin or security_officer. Writes the audit event policy.create.

Route: /v1/policies (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Name, engine, rules or Rego, priority and status of the policy.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

PoliciesResource.createBundle

createBundle(body: { revision?: string; data?: Doc } = {}, opts?: CallOptions)

Publish an OPA bundle. Packs the opa policies of the tenant into a signed OPA bundle and stores it as the new current revision. Active policies are decided by OPA; draft ones ship as libraries; disabled ones are left out. No opa policy answers 409 policy_bundle_empty; no signing key in production 503 policy_bundle_signing_unavailable. Needs tenant_admin or security_officer. Writes the audit event policy.bundle_publish. Answers 201 with the bundle record.

Route: /v1/policies/bundles (POST).

Name	Type	Default	Required	Description
body	{ revision?: string; data?: Doc }	{}	no	Optional revision name and data.json content. An empty body generates the revision.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

PoliciesResource.decisions

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

List the policy decisions. Lists the decisions of the tenant, newest first, paginated: subject, action, resource, context, allow, policy and version, reasons, obligations, engine and date. Needs tenant_admin, security_officer or auditor.

Route: /v1/policies/decisions (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).

PoliciesResource.delete

delete(id: string, opts?: CallOptions)

Delete a policy. Deletes the policy and appends a delete revision. An OPA policy pushed directly to OPA is removed from it too (503 policy_engine_unavailable when OPA cannot be reached). Needs tenant_admin or security_officer. Writes the audit event policy.delete. Answers 204, or 404 not_found.

Route: /v1/policies/{policy_id} (DELETE).

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

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

PoliciesResource.diffRevisions

diffRevisions(id: string, query: { from_revision?: number; to_revision?: number } = {}, opts?: CallOptions)

Compare two revisions of a policy. Returns the differences between two revisions of the policy. Defaults: the previous revision against the latest one. The policy is looked up first (404 not_found), then the revisions (404 not_found). Needs tenant_admin, security_officer, auditor or developer.

Route: /v1/policies/{policy_id}/revisions/diff (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the policy.
query	{ from_revision?: number; to_revision?: number }	{}	no	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).

PoliciesResource.downloadBundle

downloadBundle(revision: string = "current", opts?: CallOptions)

Download an OPA bundle. Returns the bundle OPA polls, as application/gzip: Rego modules, optional data.json, .manifest and .signatures.json (RS256 JWT over the SHA-256 of every file). The ETag header is its SHA-256 and X-Bundle-Revision its revision. Needs tenant_admin, security_officer or auditor. Answers 404 not_found for an unknown revision.

Route: /v1/policies/bundles/{revision}/bundle.tar.gz (GET).

Name	Type	Default	Required	Description
revision	string	"current"	no	Revision of the bundle, or current for the latest published one.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

PoliciesResource.engines

engines(opts?: CallOptions)

Get the policy engines status. Returns the policy services (builtin engine, OPA, OpenFGA) and the policy version or bundle revision each one really runs, read from the engine itself. Needs tenant_admin, security_officer or auditor.

Route: /v1/policies/engines (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).

PoliciesResource.evaluate

evaluate(body: PolicyContract | { request: PolicyRequest } | Doc, opts?: CallOptions)

Evaluate a policy request. Returns the decision for a Policy Contract request. The body is a Policy Contract ({schema_version, request}) or just its request object (subject, action, resource, context); it is validated against the policy-contract contract (422 validation_error).

Route: /v1/policies/evaluate (POST).

Name	Type	Default	Required	Description
body	PolicyContract | { request: PolicyRequest } | Doc		yes	Policy Contract document, or its request object alone.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

PoliciesResource.get

get(id: string, opts?: CallOptions)

Get a policy. Returns one policy. Open to any member of the tenant. Answers 404 not_found.

Route: /v1/policies/{policy_id} (GET).

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

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

PoliciesResource.list

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

List the policies. Lists the policies of the tenant in evaluation order (priority, then name), with their rules or Rego. Open to any member of the tenant. next_cursor is always null.

Route: /v1/policies (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).

PoliciesResource.listBundles

listBundles(opts?: CallOptions)

List the OPA bundles. Lists the OPA bundles published for the tenant: revision, SHA-256, signature state, policies included and date. Needs tenant_admin, security_officer or auditor.

Route: /v1/policies/bundles (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).

PoliciesResource.replace

replace(id: string, body: Doc, opts?: CallOptions)

Replace a policy. Replaces every field of the policy and appends an update revision. Same validation as at creation (rego for opa, unique name). An opa policy is pushed to OPA unless OPA loads bundles. Needs tenant_admin or security_officer. Writes the audit event policy.update. Answers 404 not_found for an unknown policy.

Route: /v1/policies/{policy_id} (PUT).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the policy.
body	Doc		yes	Full new content of the policy.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

PoliciesResource.revisions

revisions(id: string, opts?: CallOptions)

List the revisions of a policy. Lists the immutable revisions of the policy (one per create, update and delete, written in the same transaction), with their number, operation, author, date and content. Needs tenant_admin, security_officer, auditor or developer. Answers 404 not_found.

Route: /v1/policies/{policy_id}/revisions (GET).

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

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

PoliciesResource.simulate

simulate(body: { candidate: Doc; inputs?: Doc[]; policy_id?: string; recorded?: Doc }, opts?: CallOptions)

Simulate a candidate policy. Compares, input by input, the decisions of the active policies with those of the same set where the candidate replaces policy_id (or is added). Nothing is changed.

Route: /v1/policies/simulate (POST).

Name	Type	Default	Required	Description
body	{ candidate: Doc; inputs?: Doc[]; policy_id?: string; recorded?: Doc }		yes	Candidate policy, policy replaced, inputs and number of recorded decisions to replay.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class ApprovalsResource

Approvals. Human in the loop: approval requests for sensitive actions, with separation of duties, quorum and expiry. Agent runs that reach a tool needing approval, promotions of models, agents, tools, skills, MCP servers or plugins, break glass grants and mandates all create approval requests here.

Resource

ApprovalsResource.cancel

async cancel(id: string, body: ApprovalCancel, opts?: CallOptions)

Cancel an approval request. Withdraws a pending request. Allowed to its requester, a tenant_admin or a security_officer (403 forbidden otherwise, the refusal being audited). The request ends cancelled and its subject reacts as to a refusal: a waiting run fails (approval_cancelled), a pending break glass grant or mandate is rejected. A request that is no longer pending answers 409 approval_closed. Writes the audit event approval.cancel with the reason. The answer carries run_state when a run is attached.

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

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the approval request.
body	ApprovalCancel		yes	Reason of the cancellation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ApprovalsResource.check

async check(id: string, opts?: CallOptions)

Get an approval request. Returns one approval request with its decisions (approver, decision, comment, date) and approvals_count. A pending request past its expiry is marked expired and its waiting run is failed. Open to any member of the tenant. Answers 404 approval_not_found.

Route: /v1/approvals/{approval_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the approval request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ApprovalsResource.create

create(body: Doc, opts?: CallOptions)

Request an approval. Creates a pending approval request. Needs tenant_admin, developer, agent, security_officer or finops.

Route: /v1/approvals (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Action, resource, quorum, approvers and expiry of the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ApprovalsResource.decide

decide(id: 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
id	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).

ApprovalsResource.get

get(id: string, opts?: CallOptions)

Get an approval request. Returns one approval request with its decisions (approver, decision, comment, date) and approvals_count. A pending request past its expiry is marked expired and its waiting run is failed. Open to any member of the tenant. Answers 404 approval_not_found.

Route: /v1/approvals/{approval_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the approval request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ApprovalsResource.iterate

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

List the approval requests. Lists the approval requests of the tenant, newest first, paginated, optionally filtered by status. Pending requests past their expiry are marked expired first. Each item carries its decisions and approvals_count. Open to any member of the tenant.

Route: /v1/approvals (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).

ApprovalsResource.list

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

List the approval requests. Lists the approval requests of the tenant, newest first, paginated, optionally filtered by status. Pending requests past their expiry are marked expired first. Each item carries its decisions and approvals_count. Open to any member of the tenant.

Route: /v1/approvals (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 ApprovalCancel

Body of POST /v1/approvals/{id}/cancel.

Fields:

Name	Type	Required	Description
reason	string	yes	Why the request is withdrawn, kept in the audit event approval.cancel.

Class RiskResource

Risk and compliance. Risk management of the AI systems of the tenant: EU AI Act assessments, controls mapped to ISO/IEC 42001, NIST AI RMF, GDPR and the EU AI Act, evidence and time limited exceptions.

Resource

RiskResource.createAssessment

createAssessment(body: Doc, opts?: CallOptions)

Assess the risk of an AI system. Classifies the target under the EU AI Act and records the assessment. Needs tenant_admin, security_officer, developer or ai_governance_officer; the status approved needs tenant_admin, security_officer or ai_governance_officer (403 forbidden).

Route: /v1/risk/assessments (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Target, use cases, answers, owner, status and evidence of the assessment.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RiskResource.createControl

createControl(body: Doc, opts?: CallOptions)

Adopt or update a control. Creates or updates the control of the given code. For a catalogue code, the title and frameworks default to the catalogue ones. Needs tenant_admin or security_officer. Errors 400 invalid_request: status other than planned, implemented, partially_implemented or not_applicable; no title for a custom code; a framework other than iso_42001, nist_ai_rmf, gdpr or eu_ai_act. Evidence given is added. Writes the audit event risk.control.upsert.

Route: /v1/risk/controls (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Code, title, frameworks, status, owner and evidence of the control.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RiskResource.createException

createException(body: Doc, opts?: CallOptions)

Request a control exception. Records a time limited exception on a control (control_id or control_code) or on a target (target_ref). Needs tenant_admin, security_officer or developer.

Route: /v1/risk/exceptions (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Control or target, reason, compensating controls, approver and expiry.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RiskResource.evidence

evidence(query?: Query, opts?: CallOptions)

Get the compliance evidence. Returns the evidence recorded on controls and assessments, newest first, plus evidence collected automatically from the platform and mapped to the catalogue controls: counts of agents, tools, models, assessments, enabled DLP rules and retention policies, keys, audit events and exports with the state of the audit chain, evaluations, red team runs, incidents and approvals. Open to any member of the tenant.

Route: /v1/risk/evidence (GET).

Name	Type	Default	Required	Description
query	Query		no	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).

RiskResource.listAssessments

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

List the risk assessments. Lists the assessments of the tenant, newest first, at most 500, optionally for one target. Each item gives the target, eu_ai_act_category (also as risk_level), use cases, answers, rationale, obligations, status and owner. Open to any member of the tenant. next_cursor is always null.

Route: /v1/risk/assessments (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).

RiskResource.listControls

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

List the controls. Lists the controls adopted by the tenant, ordered by code, each with evidence_count, its exceptions and active_exceptions, and the builtin catalog with adopted telling which ones the tenant uses. Open to any member of the tenant.

Route: /v1/risk/controls (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).

RiskResource.listExceptions

listExceptions(query?: { status?: string } & Query, opts?: CallOptions)

List the exceptions. Lists the exceptions of the tenant ordered by expiry, each with its computed status: active, expired or revoked. Open to any member of the tenant. next_cursor is always null.

Route: /v1/risk/exceptions (GET).

Name	Type	Default	Required	Description
query	{ status?: string } & Query		no	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).

Class IncidentsResource

Incidents. Security and operations incidents of the tenant: severity, status, timeline, containment actions, Alertmanager alerts and forwarding to the SIEM.

Resource

IncidentsResource.action

action(id: string, body: { action: string; target: string; reason?: string } & Doc, opts?: CallOptions)

Run a containment action. Runs a containment action through the domain that owns the target and records it on the incident. Needs tenant_admin or security_officer.

Route: /v1/incidents/{incident_id}/actions (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the incident.
body	{ action: string; target: string; reason?: string } & Doc		yes	Action, target and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

IncidentsResource.create

create(body: Doc, opts?: CallOptions)

Open an incident. Opens an incident in status open, adds the created entry to the timeline and forwards it to the SIEM. Needs tenant_admin, security_officer, developer or agent. An unknown severity answers 400 invalid_request. Writes the audit event incident.create. The answer (201) carries the incident with its timeline.

Route: /v1/incidents (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Title, severity, description, category, resources and assignee.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

IncidentsResource.get

get(id: string, opts?: CallOptions)

Get an incident. Returns the incident with its timeline (kind, message, data, actor, date) and its containment actions (action, target, status, result). Open to any member of the tenant. Answers 404 not_found.

Route: /v1/incidents/{incident_id} (GET).

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

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

IncidentsResource.list

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

List the incidents. Lists the incidents of the tenant, newest identifier first, paginated, optionally filtered by status and severity. Items do not carry the timeline nor the actions (read one incident for those). Open to any member of the tenant.

Route: /v1/incidents (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).

IncidentsResource.receiveAlerts

receiveAlerts(body: Doc, opts?: CallOptions)

Receive Alertmanager alerts. Webhook receiver of Prometheus Alertmanager (payload version 4). Each alert is keyed by its fingerprint:

Route: /v1/incidents/alerts (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Alertmanager webhook payload, at most 500 alerts.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

IncidentsResource.update

update(id: string, body: Doc, opts?: CallOptions)

Update an incident. Changes the status, severity or assignee and optionally adds a note. Each change is added to the timeline and forwarded to the SIEM; moving to resolved or closed sets resolved_at. Needs tenant_admin or security_officer. An unknown status or severity answers 400 invalid_request. Writes the audit event incident.update.

Route: /v1/incidents/{incident_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the incident.
body	Doc		yes	Fields to change and an optional note.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class GovernanceResource

Governance. Governance registry: one aggregated view of the AI assets of the tenant, to know what exists, who owns it and how risky it is.

Resource

GovernanceResource.registry

registry(query?: Query, opts?: CallOptions)

Read the governance registry. Inventory of agents, models, providers, tools, skills, plugins and connectors (5000 items per kind at most, by name), one list per kind (agents, models, ...), with a summary per kind: total, count by status, count by risk level (unassessed when none) and number of items without owner. missing_sources lists the tables not installed on this instance; their list is empty. Requires a tenant principal (403 tenant_required). An unknown kind answers 400 invalid_request with the allowed kinds.

Route: /v1/governance/registry (GET).

Name	Type	Default	Required	Description
query	Query		no	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).

Class SecretsResource

Secrets. Write only store of the tenant secrets: provider keys, connector passwords, tokens of MCP servers. Values are encrypted (in OpenBao when configured, otherwise with AES-GCM in the database) and are never returned by the API. Other objects refer to a secret by its path; the platform reads the value server side only when it needs it.

Resource

SecretsResource.delete

delete(path: string, opts?: CallOptions)

Delete a secret. Deletes the secret and, with OpenBao, its value in the vault. Needs tenant_admin, security_officer or developer; a developer only deletes the secrets they wrote (403 forbidden). Objects that still refer to the path stop working. Writes the audit event secret.delete. Answers 204, 404 not_found, or 502 secret_backend_error when the vault cannot be reached.

Route: /v1/secrets/{path} (DELETE).

Name	Type	Default	Required	Description
path	string		yes	Path of the secret, slashes included, for example connectors/crm/password.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SecretsResource.list

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

List the secrets. Lists the metadata of the tenant secrets ordered by path: id, path, backend (openbao or local), version, created_by, created_at, updated_at. Never the value. Open to any member of the tenant. next_cursor is always null.

Route: /v1/secrets (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).

SecretsResource.write

write(body: { path: string; value: string } & Doc, opts?: CallOptions)

Write a secret. Creates the secret, or replaces its value when the path exists (the version grows by one). Needs tenant_admin, security_officer or developer; a developer only overwrites the secrets they wrote (403 forbidden). A path with a .. segment answers 400 invalid_request. The answer (201) gives the metadata, never the value. Writes the audit event secret.write. 502 secret_backend_error when the vault cannot be reached.

Route: /v1/secrets (POST).

Name	Type	Default	Required	Description
body	{ path: string; value: string } & Doc		yes	Path and value of the secret.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Interface SecuritySettings

Security settings of the tenant, read and partly updated through /v1/security/settings.

Fields:

Name	Type	Required	Description
prompt_injection_mode	"off" | "detect" | "block"	no	Prompt injection screen: off, detect or block.
untrusted_content_wrapping	boolean	no	Whether untrusted content is wrapped before it reaches the model.
output_links	"allow" | "strip_untrusted"	no	Handling of links in model output: allow or strip_untrusted.
output_link_allowlist	string[]	no	Link targets kept in model output.
egress_allowed_hosts	string[]	no	Hosts outbound calls may reach.

Class SecurityResource

Security posture and settings (/v1/security), incident report and containment of a run.

Resource

SecurityResource.cancelRun

cancelRun(runId: string, body: { reason?: string } = {}, opts?: CallOptions)

Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.

Route: /v1/runs/{run_id}/cancel (POST).

Name	Type	Default	Required	Description
runId	string		yes	Identifier (UUID) of the run.
body	{ reason?: string }	{}	no	Optional reason of the cancellation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SecurityResource.checkState

checkState(opts?: CallOptions)

Get the security posture. Returns environment, generated_at, protections (authentication methods and other protections in force), checks (each with its status pass, warn or fail, severity and message) and summary (number of checks per status). For a caller with a tenant, also tenant with the security settings of the tenant, which some checks take into account. Needs security_officer or tenant_admin. Read only.

Route: /v1/security/posture (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).

SecurityResource.getSettings

getSettings(opts?: CallOptions)

Get the security settings. Returns tenant_id and settings: the security settings of the tenant, defaults included. Needs tenant_admin or security_officer and a tenant (403 tenant_required).

Route: /v1/security/settings (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).

SecurityResource.posture

posture(opts?: CallOptions)

Get the security posture. Returns environment, generated_at, protections (authentication methods and other protections in force), checks (each with its status pass, warn or fail, severity and message) and summary (number of checks per status). For a caller with a tenant, also tenant with the security settings of the tenant, which some checks take into account. Needs security_officer or tenant_admin. Read only.

Route: /v1/security/posture (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).

SecurityResource.reportIncident

reportIncident(body: { title: string; severity?: string } & Doc, opts?: CallOptions)

Open an incident. Opens an incident in status open, adds the created entry to the timeline and forwards it to the SIEM. Needs tenant_admin, security_officer, developer or agent. An unknown severity answers 400 invalid_request. Writes the audit event incident.create. The answer (201) carries the incident with its timeline.

Route: /v1/incidents (POST).

Name	Type	Default	Required	Description
body	{ title: string; severity?: string } & Doc		yes	Title, severity, description, category, resources and assignee.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SecurityResource.updateSettings

updateSettings(body: SecuritySettings, opts?: CallOptions)

Update the security settings. Partial update: only the settings sent change, the others keep their value. Needs tenant_admin or security_officer and a tenant.

Route: /v1/security/settings (PUT).

Name	Type	Default	Required	Description
body	SecuritySettings		yes	JSON object with the settings to change, for example {"prompt_injection_mode": "block"}.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Functions

confirmCheck

confirmCheck(answer: T): T &

Returns an authz check answer only when OpenFGA gave an explicit boolean decision.

Name	Type	Default	Required	Description
answer	T		yes	Answer of POST /v1/authz/check.

Returns: T &. The same answer, typed with a boolean allowed; throws AuthzUnconfirmedError otherwise.

confirmDecision

confirmDecision(answer: Doc): PolicyDecision

Evaluate a policy request. Returns the decision for a Policy Contract request. The body is a Policy Contract ({schema_version, request}) or just its request object (subject, action, resource, context); it is validated against the policy-contract contract (422 validation_error).

Route: /v1/policies/evaluate (POST).

Name	Type	Default	Required	Description
answer	Doc		yes	Answer of POST /v1/policies/evaluate; its decision.allow must be a boolean.

Returns: PolicyDecision. Decoded JSON answer of the operation "Evaluate a policy request".

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