Skip to content

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.

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.

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.

A common task: bring a new user into an organization.

  1. POST /v1/organizations/invitations with invitationType: "organization_invitation", the organizationUid, the recipient’s email, and optionally the roleNames and groupAssignments to apply on acceptance.
  2. The recipient receives an email with a link to the invitation.
  3. 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}.

  • List my organizations. Hit /v1/me/organizations-with-roles (the Me API) rather than scanning /v1/organizations; the /me route 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, and member.