A buyer organization is one of your customers. It holds the subscription, its entitlements are what your backend rules on, and its usage is counted against its plan. End users work inside it as members, each with a role. This page covers the organization and its members; the endpoints are in the Public API reference.
Where organizations come from
End users do not create organizations. An organization appears in one of two ways:
- An end user signs up without an invitation. ShipRev creates their organization with them as its owner; see What a new account creates.
- An end user who belongs to no organization signs in again, for example after being removed from the only one they were in. ShipRev creates an organization of their own, with them as owner, before issuing the session.
Everyone else joins an existing organization by invitation. Owners and admins can rename their organization with PATCH /public/v1/organizations/{orgId}; the name is 1 to 100 characters.
In the operator console, Customers lists the buyer organizations of your application.
Roles
| Role | Can |
|---|---|
| Owner | Everything an admin can, and manage other owners |
| Admin | Change billing and the subscription, rename the organization, invite members, change roles, remove members and revoke invitations. Cannot make anyone an owner, or change or remove an owner |
| Member | See the organization, its subscription, its members and its invitations |
| Viewer | The same as a member on the Public API |
An organization always keeps at least one owner: the last owner cannot be removed or given another role.
Your backend receives the caller's organization in the session token, not their role. Decide what each end user may do in your product with the entitlements of the organization, and keep any finer permissions of your own in your application.
Invite and accept
An owner or admin invites by email:
POST /public/v1/organizations/{orgId}/invitations
Authorization: Bearer <access token of an owner or admin>
Content-Type: application/json
{ "email": "<invited email address>", "role": "MEMBER", "ttl_days": 7 }role defaults to MEMBER and ttl_days to 7. Inviting someone who is already a member, or who already has a pending invitation, is refused with 409.
ShipRev emails the invitation. The invitation token travels only in that email, never in the answer to the request, so whoever opens the link has received the mail. The link points to the hosted invitation page on your brand domain, or to your own sign-in page with an invitation_token query parameter when you have set a custom sign-in address.
The invited person then does one of two things:
| They | What happens |
|---|---|
| Already have an account on your gate | They sign in, and accept with POST /public/v1/invitations/accept and the token. The email of their account must match the invited email |
| Have no account yet | They sign up from the invitation: with a password, sending invitation_token instead of an organization name, or with Google or GitHub on the hosted page. The new account joins the inviting organization and gets no organization of its own |
Signing up from an invitation needs Allow self sign-up to be on, like any new account; see Who may create an account.
Before either, GET /public/v1/invitations/info?token=<token> shows the organization's name, the invited email, the role and the invitation's status, without a session. An invitation that is unknown answers 404, one already accepted 409, and one revoked or expired 400. Owners and admins list pending invitations and revoke them with the invitation endpoints of the organization.
Manage members
Owners and admins change a member's role with PATCH /public/v1/organizations/{orgId}/members/{membershipId} and remove a member with DELETE on the same path. Any member can remove themselves, which is how an end user leaves an organization.
Removal takes the organization out of the end user's next session; an access token they already hold names the organization until it expires, within 15 minutes. If it was their only organization, their next sign-in creates one of their own.
More than one organization
An end user can belong to several organizations of your customers, each with its own role. GET /public/v1/organizations lists them. A session is in one of them at a time:
- Sign-in starts in the organization the end user used last; after accepting an invitation, that is the inviting organization.
POST /public/v1/auth/switchwith anorganization_idmoves to another organization and returns a new access token for it.- Endpoints with
{orgId}in their path act only on the session's current organization. Switch first to work in another one.
How switching interacts with renewing the session is described in Switching organizations.