Skip to main content

Users

Read platform users, manage your own profile, and administer users.

Access it as client.users on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate)  # filters: search, archived, active, sort
for user in client.users.list():
    print(user.id)

Methods​

Core​

list​

list(*, search: str | None = None, archived: bool | None = None, active: bool | None = None, sort: str | None = None, limit: int | None = None) -> SyncPaginator[User]

List the users you can see, newest first.

On a multi-tenant installation these are the members of your organization; otherwise every user (a platform admin sees every user).

Parameters

  • search (str | None, optional): Only users whose email address or name contains this text (case insensitive).
  • archived (bool | None, optional): True lists only archived users. The API's default (and False) lists only users who are not archived.
  • active (bool | None, optional): True lists only active users, False only deactivated ones. The API's default is both.
  • sort (str | None, optional): The order, as comma-separated wire field names, each prefixed with - for descending, on the stored user record (for example "profile.name"). The API's default is "-createdAt".
  • limit (int | None, optional): The most users to return; None returns every one.

Returns

  • SyncPaginator[User]: Each user's username, email and role, fetched a page at a time.

create​

create(*, email: str, name: str, role: str | None = None, send_email: bool | None = None, profile: Mapping[str, Any] | None = None) -> CreatedUser

Create a user (platform admins).

The user gets a temporary password, a default API key and an organization of their own.

Parameters

  • email (str): The user's email address, not already registered.
  • name (str): The user's display name.
  • role (str | None, optional): The user's platform role: "admin", "developer" or "app". The API's default (and its choice for any other value) is "app".
  • send_email (bool | None, optional): False sends no welcome email. The API's default emails the user a link to set their password, when the platform sends mail.
  • profile (Mapping[str, Any] | None, optional): More profile fields to store on the user, with their wire names.

Returns

  • CreatedUser: The new user's id and temporary password.

Raises

  • PermissionDeniedError: You are not a platform admin.
  • ConflictError: A user with this email already exists (error_code duplicate).
  • ValidationError: email is not a valid address.

retrieve​

retrieve(user_id: str) -> User

Retrieve a user you can see.

Parameters

  • user_id (str): The user's id.

Returns

  • User: The user's username, email and role.

Raises

  • NotFoundError: There is no such user, or it is outside your organization.

update​

update(user_id: str, *, name: str | None = None, email: str | None = None, active: bool | None = None, archived: bool | None = None, is_admin: bool | None = None, is_developer: bool | None = None) -> User

Update a user (platform admins).

Only the fields you give change. Returns the user, as retrieve does.

Parameters

  • user_id (str): The user's id.
  • name (str | None, optional): The user's display name.
  • email (str | None, optional): The user's email address; it becomes unverified.
  • active (bool | None, optional): False deactivates the user and revokes their API keys; True reactivates them and issues a new default API key.
  • archived (bool | None, optional): True archives the user and deletes their API keys; False restores them. archive also decides what happens to the user's resources.
  • is_admin (bool | None, optional): With is_developer, sets the user's one platform role: "admin" when is_admin is true, else "developer" when is_developer is true, else "app". Giving either replaces the user's role.
  • is_developer (bool | None, optional): See is_admin.

Raises

  • PermissionDeniedError: You are not a platform admin.
  • NotFoundError: There is no such user.
  • ConflictError: email belongs to another user.

Lifecycle & actions​

archive​

archive(user_id: str, *, asset_action: str | None = None, transfer_to_user_id: str | None = None) -> UserArchiveResult

Archive a user (platform admins).

The user is deactivated and signed out, and their API keys are deleted. Users are never deleted: unarchive restores one.

Parameters

  • user_id (str): The user's id; not your own.
  • asset_action (str | None, optional): What happens to the user's resources: "transfer" (to transfer_to_user_id), "transfer-to-admin" (to their organization's owner, or to you when they have no organization), "delete" or "leave-as-is", the API's default.
  • transfer_to_user_id (str | None, optional): The user who receives the resources, for "transfer" (required there): an active user in the same organization.

Returns

  • UserArchiveResult: The user, with what was done with their resources (transferred or deleted).

Raises

  • PermissionDeniedError: You are not a platform admin.
  • NotFoundError: There is no such user (or transfer target).
  • ValidationError: asset_action is not one of the four, or a transfer has no target.

Other​

assets​

assets(user_id: str) -> UserAssetSummary

Summarize the resources a user owns (platform admins).

Read it before archiving a user, to see what a transfer or deletion would affect.

Parameters

  • user_id (str): The user's id.

Returns

  • UserAssetSummary: The counts of the user's resources by type, and what deleting them would remove.

Raises

  • PermissionDeniedError: You are not a platform admin.
  • NotFoundError: There is no such user.

delete_me​

delete_me() -> AccountDeletionResult

Delete your own account.

Every resource you own is deleted, your account is archived, your API keys are deleted (including the one this client uses) and your sessions end. This cannot be undone from the API.

Returns

  • AccountDeletionResult: What was deleted (nothing, when the account was already deleted).

github_ssh_keys​

github_ssh_keys() -> list[GithubSSHKey]

List your GitHub SSH keys.

A GitHub source for an app, volume or project names one of these keys by id. Keys are added in the platform's profile settings.

Returns

  • list[GithubSSHKey]: Your keys: their public halves, never the private keys.

me​

me() -> CurrentUser

Return who you are authenticated as.

Returns

  • CurrentUser: Your user id, username, email and role, your organization, and the api_key the request used.

reset_password​

reset_password(user_id: str) -> PasswordResetResult

Start a password reset for a user (platform admins).

The user is emailed a reset link when the platform sends mail.

Parameters

  • user_id (str): The user's id.

Returns

  • PasswordResetResult: The user, with whether the link was emailed and the reset token when it was not.

Raises

  • PermissionDeniedError: You are not a platform admin.
  • NotFoundError: There is no such user.
  • UnprocessableEntityError: The user has no email address.

unarchive​

unarchive(user_id: str) -> User

Restore an archived user (platform admins).

The user is active again.

Parameters

  • user_id (str): The user's id.

Returns

  • User: The user, active again.

Raises

  • PermissionDeniedError: You are not a platform admin.
  • NotFoundError: There is no such user.

update_me​

update_me(*, name: str | None = None, photo: str | None = None, stan_personality: str | None = None) -> CurrentUser

Update your own profile.

Only the fields you give change. Returns you, as me does.

Parameters

  • name (str | None, optional): Your display name (an empty name is ignored).
  • photo (str | None, optional): Your profile photo, as a URL or a base64 data URL.
  • stan_personality (str | None, optional): How STAN talks to you: "professional", "friendly" or "concise".

Raises

  • ValidationError: stan_personality is not one of the three.