Skip to main content

Organizations

Read and manage your organization: its details, members, invitations and credits.

Access it as client.organizations 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: status
for organization in client.organizations.list():
    print(organization.id)

# Retrieve one by id
item = client.organizations.retrieve("<id>")

Methods​

Core​

list​

list(*, status: str | None = None, limit: int | None = None) -> SyncPaginator[Organization]

List organizations, newest first.

A platform admin sees every organization; anyone else the organizations they are an active member of.

Parameters

  • status (str | None, optional): Only organizations with this status: "active", "suspended" or "archived". The API's default is every organization that is not archived.
  • limit (int | None, optional): The most organizations to return; None returns every one.

Returns

  • SyncPaginator[Organization]: The organizations, fetched a page at a time.

retrieve​

retrieve(org_id: str) -> Organization

Retrieve an organization you are a member of.

Parameters

  • org_id (str): The organization's id.

Returns

  • Organization: The organization.

Raises

  • PermissionDeniedError: You are not a member of the organization (also when it does not exist) and not a platform admin.

update​

update(org_id: str, *, name: str | None = None, description: str | None = None, status: str | None = None, billing_email: str | None = None, settings: Mapping[str, Any] | None = None, alert_thresholds: Sequence[int] | None = None) -> Organization

Update an organization (its owners and admins, or a platform admin).

Only the fields you give change.

Parameters

  • org_id (str): The organization's id.
  • name (str | None, optional): The organization's name.
  • description (str | None, optional): Its description.
  • status (str | None, optional): "active", "suspended" or "archived". On a multi-tenant installation only a platform admin may change it.
  • billing_email (str | None, optional): Where billing email goes.
  • settings (Mapping[str, Any] | None, optional): Settings merged into the current ones: any of timezone, currency and fiscalYearStart.
  • alert_thresholds (Sequence[int] | None, optional): Balances, in US cents, at which an alert is sent. Billing-enabled platforms only.

Returns

  • Organization: The updated organization.

Raises

  • PermissionDeniedError: You are not an owner or admin of the organization.
  • ConflictError: A credit setting was given and billing is not enabled (error_code billing-disabled); nothing was changed.

Other​

add_credits​

add_credits(org_id: str, *, amount: int, note: str | None = None) -> CreditTransaction

Add credits to an organization (platform admins).

The credits go to the purchased pool and expire after 90 days.

Parameters

  • org_id (str): The organization's id.
  • amount (int): The credits to add, in US cents (a positive whole number).
  • note (str | None, optional): Why they were added; shown on the transaction.

Returns

  • CreditTransaction: The admin_allocation transaction.

Raises

  • ConflictError: Billing is not enabled (error_code billing-disabled).
  • PermissionDeniedError: You are not a platform admin.
  • ValidationError: amount is not a positive whole number of cents.

add_member​

add_member(org_id: str, *, user_id: str, role: str | None = None) -> Member

Add an existing user to an organization.

On a multi-tenant installation only a platform admin may; invite new members with invite.

Parameters

  • org_id (str): The organization's id.
  • user_id (str): The user to add.
  • role (str | None, optional): Their organization role: "admin", "member" or "viewer". The API's default is "member".

Returns

  • Member: The new membership.

Raises

  • PermissionDeniedError: You are not an owner or admin of the organization.
  • NotFoundError: There is no such user.
  • ValidationError: role is not one of the three.

cancel_invitation​

cancel_invitation(org_id: str, invitation_id: str) -> None

Cancel a pending invitation.

Parameters

  • org_id (str): The organization's id.
  • invitation_id (str): The invitation's id.

Raises

  • NotFoundError: There is no pending invitation with this id.
  • PermissionDeniedError: You are not an owner or admin of the invitation's organization.

credits​

credits(org_id: str) -> OrganizationCredits

Return an organization's credit balance (its members, or a platform admin).

Parameters

  • org_id (str): The organization's id.

Returns

  • OrganizationCredits: The balance and its pools, in US cents, and the credit settings.

Raises

  • ConflictError: Billing is not enabled on this platform (error_code billing-disabled).
  • PermissionDeniedError: You are not a member of the organization.

invite​

invite(org_id: str, *, email: str, role: str, platform_role: str | None = None, name: str | None = None) -> Invitation

Invite someone to join an organization by email.

The invitation expires after 7 days. It is emailed when the platform sends mail.

Parameters

  • org_id (str): The organization's id.
  • email (str): The invitee's email address.
  • role (str): Their organization role: "admin" or "member", or (single-tenant) "viewer".
  • platform_role (str | None, optional): Multi-tenant (required there): their platform role, "developer" or "app".
  • name (str | None, optional): Multi-tenant: the invitee's display name.

Returns

  • Invitation: The invitation just sent.

Raises

  • PermissionDeniedError: You are not an owner or admin of the organization.
  • ConflictError: The address already has a pending invitation or is already a member.
  • ValidationError: role (or platform_role) is not a valid one.

list_invitations​

list_invitations(org_id: str) -> list[Invitation]

List an organization's pending invitations, newest first.

Parameters

  • org_id (str): The organization's id.

Returns

  • list[Invitation]: The pending invitations.

Raises

  • PermissionDeniedError: You are not an owner or admin of the organization.

list_members​

list_members(org_id: str) -> list[Member]

List an organization's active members.

Parameters

  • org_id (str): The organization's id.

Returns

  • list[Member]: The members, with their email addresses, names and roles.

Raises

  • PermissionDeniedError: You are not a member of the organization.

list_transactions​

list_transactions(org_id: str, *, type: str | None = None, limit: int | None = None) -> SyncPaginator[CreditTransaction]

List an organization's credit transactions, newest first.

Parameters

  • org_id (str): The organization's id.
  • type (str | None, optional): Only transactions of this type (for example "usage_charge" or "admin_allocation"). The API's default is every type.
  • limit (int | None, optional): The most transactions to return; None returns every one.

Returns

  • SyncPaginator[CreditTransaction]: The transactions, fetched a page at a time.

Raises

  • ConflictError: Billing is not enabled (error_code billing-disabled).
  • PermissionDeniedError: You are not a member of the organization.

remove_member​

remove_member(org_id: str, user_id: str) -> MemberRemoval

Remove a member from an organization.

The member's resources in the organization are transferred to its owner. On a multi-tenant installation the member's account is also archived.

Parameters

  • org_id (str): The organization's id.
  • user_id (str): The member's user id; not the owner.

Returns

  • MemberRemoval: What was transferred, and to whom.

Raises

  • PermissionDeniedError: You are not an owner or admin of the organization.
  • NotFoundError: There is no such organization.

resend_invitation​

resend_invitation(org_id: str, invitation_id: str) -> None

Send a pending invitation again, with a new link and a fresh 7 days.

Multi-tenant installations only.

Parameters

  • org_id (str): The organization's id.
  • invitation_id (str): The invitation's id.

Raises

  • NotFoundError: There is no pending invitation with this id.
  • PermissionDeniedError: You may not manage the organization's invitations.
  • ConflictError: The installation is single-tenant (error_code not-supported).

update_member​

update_member(org_id: str, user_id: str, *, role: str | None = None, platform_role: str | None = None, active: bool | None = None) -> Member

Change a member's organization role, platform role or activity.

On a single-tenant installation the API reads only role, which is then required (platform_role and active are not applied). On a multi-tenant installation give any of the three.

Parameters

  • org_id (str): The organization's id.
  • user_id (str): The member's user id.
  • role (str | None, optional): Their organization role: "admin", "member" or (single-tenant) "viewer".
  • platform_role (str | None, optional): Multi-tenant: their platform role, "developer" or "app".
  • active (bool | None, optional): Multi-tenant: False deactivates the member (their sessions end and their API keys are revoked); True reactivates them.

Returns

  • Member: The member as changed.

Raises

  • PermissionDeniedError: You may not change this member (only an owner changes roles on a single-tenant installation).
  • NotFoundError: The user is not an active member.
  • ValidationError: Nothing to change was given (single-tenant: no role), or a role is not a valid one.