# client.identity.users

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

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

On `AsyncKindgi` every method is the same, awaited.

## `client.identity.users.list()`

```python signature
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
```

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()`

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

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()`

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

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

A tenant admin, or the person themselves.

## `client.identity.users.list_sessions()`

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

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()`

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

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()`

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

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()`

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

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()`

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

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()`

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

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.