client.identity.users

client.identity.users — the identity.users operations.

On AsyncKindgi every method is the same, awaited.

client.identity.users.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    query: str | None = None,
    include_unregistered: bool | None = None,
    include: Literal['grants'] | None = None,
    timeout: float | None = None,
) -> UserCollectionPage

Signature

List users in the tenant. GET /v1/identity/users

Cursor-paginated list of tenant users (sort order is binding-defined), for tenant admins only. Optional ?query= is a prefix match on displayName — the natural filter shape for a "search users" surface. primaryEmail may be redacted per tenant policy. Anyone else adds a person to a project by their email or id (POST /v1/projects/{projectId}/memberships).

client.identity.users.create()

create(
    body: CreateUserBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> UserRecord

Signature

Add a person. POST /v1/identity/users

Adds a person to the tenant as a tenant member, written before it answers: they can read the tenant's settings (providers, policies, adapters, signing keys, deployments), not its projects. Give them a role to work (project or team membership, or tenant admin), then mint their first API key at POST /v1/tokens with for. Tenant admins only. Mounted when the identity directory can add people.

client.identity.users.get()

get(user_id: str | UUID, /, *, timeout: float | None = None) -> UserRecord

Signature

Get a user by id. GET /v1/identity/users/{userId}

A tenant admin, or the person themselves.

client.identity.users.list_sessions()

list_sessions(
    user_id: str | UUID,
    /,
    *,
    timeout: float | None = None,
) -> IdentitySessionCollectionPage

Signature

List active sessions for a user. GET /v1/identity/users/{userId}/sessions

A tenant admin, or the person themselves. Returns the wire-safe IdentitySessionSummary shape — provider access-token + refresh-token never cross the wire, even to admins. Unknown user id returns an empty list (call GET /v1/identity/users/:userId first to distinguish "no sessions" from "no user").

client.identity.users.unregister()

unregister(
    user_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> UnregisterUserResult

Signature

Remove a person. POST /v1/identity/users/{userId}/unregister

Removes a person from the tenant, in one step: they're marked removed (unregisteredAt; their record stays, so their history still says who they were), every API key and session of theirs is revoked, and every grant and membership they hold is taken away, all before it answers. Their keys get 401 at once. Their email is free again: adding it makes a new person. Removing someone already removed changes nothing. Refused for yourself and the deployment's seed user (identity-user-unregister-refused), and for the only tenant admin (last-tenant-admin). Tenant admins only. Mounted when the identity directory can remove people.

client.identity.users.revoke_sessions()

revoke_sessions(
    user_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> RevokeSessionsResult

Signature

Revoke every active session for a user. POST /v1/identity/users/{userId}/revoke-sessions

A tenant admin revokes anyone's sessions; anyone else only their own. Idempotent. Under the hood, deployments typically delegate to SessionStoreBinding.revokeAllForUser. Returns { revokedCount: 0 } when the user was already fully signed out.

client.identity.users.grants()

grants(user_id: str | UUID, /, *, timeout: float | None = None) -> PersonGrants

Signature

Read a person's grants. GET /v1/identity/users/{userId}/grants

What the person may do, as granted directly: tenant admin, project and team roles, the reviewer roster. A tenant admin reads anyone's; anyone else only their own.

client.identity.users.grant()

grant(
    user_id: str | UUID,
    body: PersonGrantBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PersonGrants

Signature

Make a person a tenant admin. POST /v1/identity/users/{userId}/grant

Written before the call answers, so the person's next request holds it. A no-op when held. Tenant admins only.

client.identity.users.ungrant()

ungrant(
    user_id: str | UUID,
    body: PersonGrantBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PersonGrants

Signature

Remove tenant admin from a person. POST /v1/identity/users/{userId}/ungrant

A no-op when not held. Refused for the only person who is a tenant admin (last-tenant-admin: make someone else one first), and for the seed user, whom the runtime makes tenant admin at every boot (seed-user-admin: unset KINDGI_SEED_USER_ID and restart it first). Tenant admins only.