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,
    pending: 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,
) -> UserCreated

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. A person added with an email is invited (invite): they sign in within 7 days, or a tenant admin renews it (POST /v1/identity/users/{userId}/invite); the invitation is emailed where the deployment sends email, and inviteEmail says whether it was. 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.resend_invite()

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

Signature

Renew a person's invitation. POST /v1/identity/users/{userId}/invite

For a person who hasn't signed in yet (invite pending or expired): a new expiry, 7 days on, and the invitation emailed again where the deployment sends email (inviteEmail says whether it was). A person who has signed in, was added before invitations, or has no email gets 409 identity-user-not-invited. Renewing one person again within a minute, more than 5 times in 24 hours, or past the invitation emails the workspace, or the whole deployment, may send in 24 hours, gets 429 invite-capped with Retry-After, and changes nothing. To revoke an invitation, remove the person (POST /v1/identity/users/{userId}/unregister). Tenant admins only. Mounted when the identity directory invites people (from 0.1.9).

client.identity.users.second_factor()

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

Signature

A person's second factor. GET /v1/identity/users/{userId}/second-factor

Whether they have a second factor set up, since when, how many recovery codes are left, and whether it can still be used. Never a key or a code. Tenant admins only. Mounted when the deployment keeps second factors (from 0.1.9).

client.identity.users.remove_second_factor()

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

Signature

Remove a person's second factor. POST /v1/identity/users/{userId}/second-factor/remove

For a lost phone, or lost recovery codes: their key is deleted, their recovery codes stop working, they're told by email where the deployment sends it, and it's audited. Their sessions stay: removing one gives no one access. Where the workspace requires one, they set one up at their next sign-in. removed: false when they had none. Tenant admins only, for anyone but themselves: an admin's own is taken off at POST /v1/identity/me/second-factor/remove, with a code from it (403 permission-denied here). Mounted when the deployment keeps second factors (from 0.1.9).

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.