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). |
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.