Organizations
The Organization API covers organizations, their memberships, roles, and invitations. If you’re managing institutional accounts, group membership, or RBAC permissions, this is the surface.
For user-side operations (the individual user record), see the User and Me APIs.
Endpoints at a glance
Section titled “Endpoints at a glance”| Resource | What it is |
|---|---|
/v1/organizations, /v1/organizations/{slug} |
Organization records — institutional owners |
/v1/organizations/{slug}/members, /members-with-roles, /memberships |
Members of the organization and their roles |
GET /v1/organizations/{slug}/invitations |
Invitations to join the organization |
POST /v1/organizations/invitations |
Invite someone by email (/invitations/batch for several) |
GET /v1/organizations/{slug}/roles |
The organization’s role definitions |
/v1/organizations/{slug}/groups |
Groups within the organization |
Groups also have their own endpoints under /v1/groups (members, roles, invitations); they share many of the same patterns as organizations.
Permissions
Section titled “Permissions”Organization-level operations require either:
- Membership with sufficient role — the roles a member holds in the organization grant its permissions (manage members, manage groups, manage devices, manage observing, etc.).
- Skynet admin authority — for Skynet staff operating on organizations they don’t directly belong to.
For the model behind this, see Entities.
Invitation flow
Section titled “Invitation flow”A common task: bring a new user into an organization.
POST /v1/organizations/invitationswithinvitationType: "organization_invitation", theorganizationUid, the recipient’semail, and optionally theroleNamesandgroupAssignmentsto apply on acceptance.- The recipient receives an email with a link to the invitation.
- The recipient accepts it in the web app, which creates the membership and applies the assigned roles.
An organization can also create a shareable open invitation link with POST /v1/organizations/{slug}/invitations/open. Invitations can be revoked before acceptance with DELETE /v1/invitations/{uid}.
Common task recipes
Section titled “Common task recipes”- List my organizations. Hit
/v1/me/organizations-with-roles(the Me API) rather than scanning/v1/organizations; the/meroute is filtered to your memberships. - Add an org-owned telescope. Telescope and observatory registration is handled by Skynet staff (the create endpoints, such as
POST /v1/organizations/{slug}/telescopes, are staff-only). See Onboarding. - Change a member’s roles.
PUT /v1/organizations/{slug}/members/{userUid}(the member’s user uid) with the full list of role names the member should hold. Role names are a fixed set shared by every organization:owner,membership_manager,group_manager,observing_manager,device_manager,telescope_viewer, andmember.