Skip to content

Organizations & Roles

Endpoints for managing organization membership and role-based access. These are primarily used by the Portal; they require portal-user permissions, not M2M scopes.

Current user & profile

Method Path Purpose
GET /portal/current-user The signed-in user's profile and organization memberships.
PATCH /portal/me Update the current user's profile: first name, last name, phone number. The email address cannot be changed here.
GET /portal/check-email Check whether an email is already in use by another user.
GET /organizations/users List the members of the organization named by organizationId. Requires org_members:read. Searchable and sortable, in page mode or batch mode — see Lists: page mode and batch mode.

Membership

Method Path Permission Purpose
POST /org/{orgId}/members org_members:write Invite a user to the organization (creates a Cognito user if needed).
POST /org/{orgId}/members/{userId}/resend-invitation org_members:write Send the invitation email again to a member who has not accepted yet.
DELETE /org/{orgId}/members/{userId} org_members:write Remove a user from the organization.

These three need a signed-in user; an app client is refused with 403 even when it holds the permission.

Roles & permissions

Method Path Permission Purpose
GET /org/{orgId}/permissions org_roles:read List the permissions available in the organization.
GET /org/{orgId}/roles org_roles:read List roles.
GET /org/{orgId}/roles/{roleId} org_roles:read Get one role.
POST /org/{orgId}/roles org_roles:write Create a custom role.
PUT /org/{orgId}/roles/{roleId} org_roles:write Update a role.
DELETE /org/{orgId}/roles/{roleId} org_roles:write Delete a role.

Role assignment

Assigning roles is part of managing members, so these routes check the member permissions, not the role permissions.

Method Path Permission Purpose
GET /org/{orgId}/members/{userId}/roles org_members:read List a member's role assignments.
POST /org/{orgId}/members/{userId}/roles org_members:write Assign a role to a member.
DELETE /org/{orgId}/members/{userId}/roles/{roleId} org_members:write Revoke a role from a member.

Subscription permissions

A role can grant three subscription permissions:

Permission Lets a member
subscriptions:read Read any of the organization's subscriptions, and list them one app client at a time.
subscriptions:delete Delete any of the organization's subscriptions.
subscriptions:write Create subscriptions. Subscriptions are created by app clients, which hold this permission through the subscriptions/write:self scope rather than a role.

Ownership does not apply to members: the role alone decides which of the organization's subscriptions they can read or delete. An app client reaches only the subscriptions it created. See Authentication and Subscriptions.

Refusals

Creating or updating a role, and creating an organization, answer 409 with a stable code beside the error sentence when the value is already in use:

Status Code When
409 SLUG_TAKEN The slug is already in use.
409 NAME_TAKEN The name is already in use (for a role, within the organization).
{ "error": "A role with this name already exists in the organization", "code": "NAME_TAKEN" }

Some other 409s carry error alone: removing a member, or revoking a role, that would leave the organization with nobody able to manage members and roles; and resending an invitation that has already been accepted. See Errors and codes.

Creating organizations

Creating a brand-new organization (POST /portal/organizations) is gated behind a license key and is not part of routine self-service. Talk to the platform owner if you need a new organization provisioned.