enterprise_ai.identity

Source: sdks/python/src/enterprise_ai/identity/__init__.py. Back to the Python 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 IdentityClient

/v1/me, /v1/members, /v1/api-keys, /v1/service-identities, /v1/authz, /v1/secrets, /v1/identity/quota-profiles and /v1/identity/group-mappings.

Resource

IdentityClient.add_member

add_member(user: str, role: str, **extra: Any) -> Any

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
user	str		yes	Subject of the user: the OIDC sub claim, 1 to 200 characters.
role	str		yes	Role given: platform_admin, tenant_admin, security_officer, finops, developer, auditor, agent, viewer, soc_analyst, ai_governance_officer, data_steward, application_owner, ai_platform_engineer, business_owner or support_engineer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Add a member".

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

IdentityClient.assume_service

assume_service(identity_id: str, purpose: str, audience: list[str] | None = None, ttl_seconds: int | None = None, scopes: list[str] | None = None) -> Any

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
identity_id	str		yes	Identifier (UUID) of the service identity.
purpose	str		yes	Why the identity is assumed, 3 to 500 characters. Written to the audit trail and the signed context.
audience	list[str] | None	None	no	Services allowed to accept the context, 1 to 10 known audiences. Null: the default audience of the Context Authority.
ttl_seconds	int | None	None	no	Lifetime of the context in seconds, 30 to 3600 (default 900).
scopes	list[str] | None	None	no	Scopes requested, at most 50. Default: the scopes of the identity. Each must be granted by the identity and held by the caller.

Returns: Any. Decoded JSON answer of the operation "Assume a service identity".

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

IdentityClient.change_password

change_password(current_password: str, new_password: str) -> Any

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
current_password	str		yes	Current password, 1 to 256 characters.
new_password	str		yes	New password: at least the configured minimum length (12 by default), at most 256 characters, with letters and non letters.

Returns: Any. Decoded JSON answer of the operation "Change the password".

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

IdentityClient.check

check(subject: str, relation: str, object: str) -> Any

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
subject	str		yes	Subject checked, <type>:<id>: user:alice, group:fin#member or user:*.
relation	str		yes	Relation name, lowercase letters, digits and underscores, for example viewer.
object	str		yes	Object checked, <type>:<id>, for example project:42.

Returns: Any. Decoded JSON answer of the operation "Check a relation".

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

IdentityClient.create_api_key

create_api_key(name: str, scopes: list[str], **extra: Any) -> Any

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
name	str		yes	Display name of the key, 1 to 200 characters, for example the pipeline that uses it.
scopes	list[str]		yes	Scopes granted to the credential, as glob patterns (models:invoke, admin:*). Each scope must be held by the caller (403 forbidden, reason scope_not_held). Empty list by default.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create an API key".

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

IdentityClient.create_group_mapping

create_group_mapping(group: str, **fields: Any) -> Any

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
group	str		yes	Group name as found in the groups or entra_groups claim, 1 to 256 characters, matched exactly.
**fields	Any		no	Fields of the method (for example user and password), up to 16 text values.

Returns: Any. Decoded JSON answer of the operation "Create a group mapping".

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

IdentityClient.create_quota_profile

create_quota_profile(name: str, **fields: Any) -> Any

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
name	str		yes	Unique name of the profile in the tenant, 1 to 200 characters.
**fields	Any		no	Fields of the method (for example user and password), up to 16 text values.

Returns: Any. Decoded JSON answer of the operation "Create a quota profile".

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

IdentityClient.create_service_identity

create_service_identity(name: str, spiffe_id: str, **extra: Any) -> Any

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
name	str		yes	Name of the identity, 1 to 200 characters; the subject becomes service:<name>.
spiffe_id	str		yes	SPIFFE ID of the workload, spiffe://<trust domain>/<path>, unique on the platform.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a service identity".

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

IdentityClient.delete_group_mapping

delete_group_mapping(mapping_id: str) -> Any

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
mapping_id	str		yes	Identifier (UUID) of the group mapping.

Returns: Any. Decoded JSON answer of the operation "Delete a group mapping".

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

IdentityClient.delete_quota_profile

delete_quota_profile(profile_id: str) -> Any

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
profile_id	str		yes	Identifier (UUID) of the quota profile.

Returns: Any. Decoded JSON answer of the operation "Delete a quota profile".

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

IdentityClient.delete_secret

delete_secret(path: str) -> Any

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	str		yes	Path of the secret, slashes included, for example connectors/crm/password.

Returns: Any. Decoded JSON answer of the operation "Delete a secret".

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

IdentityClient.delete_service_identity

delete_service_identity(identity_id: str) -> Any

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
identity_id	str		yes	Identifier (UUID) of the service identity.

Returns: Any. Decoded JSON answer of the operation "Delete a service identity".

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

IdentityClient.delete_tuples

delete_tuples(tuples: list[dict[str, str]]) -> Any

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
tuples	list[dict[str, str]]		yes	Relation tuples to delete, each {subject, relation, object} (1 to 100).

Returns: Any. Decoded JSON answer of the operation "Delete authorization tuples".

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

IdentityClient.get_group_mapping

get_group_mapping(mapping_id: str) -> Any

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
mapping_id	str		yes	Identifier (UUID) of the group mapping.

Returns: Any. Decoded JSON answer of the operation "Get a group mapping".

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

IdentityClient.list_api_keys

list_api_keys(**page: Any) -> Any

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
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the API keys".

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

IdentityClient.list_group_mappings

list_group_mappings() -> Any

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).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the group mappings".

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

IdentityClient.list_members

list_members(**page: Any) -> Any

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
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the members".

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

IdentityClient.list_quota_profiles

list_quota_profiles() -> Any

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).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the quota profiles".

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

IdentityClient.list_secrets

list_secrets(**page: Any) -> Any

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
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the secrets".

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

IdentityClient.list_service_identities

list_service_identities(**page: Any) -> Any

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
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the service identities".

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

IdentityClient.list_tuples

list_tuples(subject: str | None = None, object: str | None = None, **page: Any) -> Any

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
subject	str | None	None	no	Only the tuples of this subject, such as user:alice or group:fin#member.
object	str | None	None	no	Only the tuples on this object, <type>:<id> such as project:42.
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List authorization tuples".

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

IdentityClient.login

login(username: str, password: str) -> Any

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
username	str		yes	Login of the account, 1 to 128 characters, compared without case.
password	str		yes	Password, 1 to 256 characters. Write only: never returned nor logged.

Returns: Any. Decoded JSON answer of the operation "Sign in with a login and a password".

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

IdentityClient.logout

logout() -> Any

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).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Sign out".

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

IdentityClient.me

me() -> Any

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).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Read the current principal".

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

IdentityClient.put_secret

put_secret(path: str, value: str) -> Any

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
path	str		yes	Path of the secret, 1 to 255 characters among letters, digits, _, ., / and -, not starting with ., / or -.
value	str		yes	Secret value, 1 to 65536 characters. Write only: encrypted at rest, never returned nor logged.

Returns: Any. Decoded JSON answer of the operation "Write a secret".

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

IdentityClient.remove_member

remove_member(member_id: str) -> Any

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
member_id	str		yes	Identifier (UUID) of the membership.

Returns: Any. Decoded JSON answer of the operation "Remove a member".

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

IdentityClient.revoke_api_key

revoke_api_key(key_id: str) -> Any

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
key_id	str		yes	Identifier (UUID) of the API key.

Returns: Any. Decoded JSON answer of the operation "Revoke an API key".

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

IdentityClient.rotate_api_key

rotate_api_key(key_id: str) -> Any

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
key_id	str		yes	Identifier (UUID) of the API key.

Returns: Any. Decoded JSON answer of the operation "Rotate an API key".

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

IdentityClient.update_group_mapping

update_group_mapping(mapping_id: str, **changes: Any) -> Any

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
mapping_id	str		yes	Identifier (UUID) of the group mapping.
**changes	Any		no	Fields of the group mapping to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Update a group mapping".

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

IdentityClient.update_member

update_member(member_id: str, role: str | None = None, clearance: str | None = None) -> Any

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
member_id	str		yes	Identifier (UUID) of the membership.
role	str | None	None	no	New role, same values as at creation.
clearance	str | None	None	no	New clearance: public, internal, confidential, restricted or secret.

Returns: Any. Decoded JSON answer of the operation "Update a member".

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

IdentityClient.update_quota_profile

update_quota_profile(profile_id: str, **changes: Any) -> Any

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
profile_id	str		yes	Identifier (UUID) of the quota profile.
**changes	Any		no	Fields of the quota profile to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Update a quota profile".

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

IdentityClient.whoami

whoami() -> Any

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).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Show the calling identity".

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

IdentityClient.write_tuples

write_tuples(tuples: list[dict[str, str]]) -> Any

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
tuples	list[dict[str, str]]		yes	Relation tuples to write, each {subject, relation, object} such as user:alice, viewer, project:p1 (1 to 100).

Returns: Any. Decoded JSON answer of the operation "Write authorization tuples".

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

Functions

confirm_assumed

confirm_assumed(answer: Any) -> Any

Return an assumed service context only when it carries the signed token and its context_id.

Name	Type	Default	Required	Description
answer	Any		yes	Answer of the service identity assume call to check.

Returns: Any. The same answer, unchanged; otherwise AuthzUnconfirmed is raised.

Raises: AuthzUnconfirmed.