Organizations

An organization is your team account in Orbimon: members, roles, and Starlink monitors all belong to it.

Use a user (omb_user_…) or service (omb_svc_…) API token. What you can do depends on your role and the token scopes (read / write).

← API overview

What’s in an organization

Organization
├── Users (members + roles)
│     owner  — full control including deleting the organization
│     admin  — members, roles, monitor administration
│     member — access to the organization’s monitors
└── Monitors
      └── Starlink telemetry → Monitors API

Single-organization policy: each user belongs to at most one organization.

Billing / invoices are not in the public API yet. Time series: Monitors API.

Endpoint map

Email invitations for users who have not signed up yet are managed in the Orbimon dashboard (not this public surface).

Get my organization

GET /v1/organizations
Authorization: Bearer <user_or_service_token>

Response 200

{
  "data": {
    "id": "org_…",
    "name": "Acme Field Ops",
    "slug": "acme-field-ops",
    "image_url": null,
    "role": "owner",
    "created_at": "2026-01-08T14:00:00.000Z"
  }
}

Errors

Create organization

POST /v1/organizations
Authorization: Bearer <user_token>
Content-Type: application/json

{
  "name": "Acme Field Ops",
  "slug": "acme-field-ops"
}

slug is optional (derived from name when omitted). The caller becomes owner. Fails if the user already belongs to an organization. Service tokens cannot create organizations.

Response 201

Same shape as Get my organization.

Errors

Get organization

GET /v1/organizations/:org_id
Authorization: Bearer <user_or_service_token>

Returns organization details including members and monitors (dashboard-oriented payload). For the compact public lists, prefer /users and /monitors below.

Errors

Update organization

PATCH /v1/organizations/:org_id
Authorization: Bearer <user_or_service_token>
Content-Type: application/json

{
  "name": "Acme Field Ops",
  "slug": "acme-field-ops"
}

Requires owner or admin and write scope. At least one of name or slug must be sent.

Errors

Delete organization

DELETE /v1/organizations/:org_id
Authorization: Bearer <user_token>

Owner only. Deletes the organization, its memberships, and all monitors (API keys revoked).

Errors

List users

GET /v1/organizations/:org_id/users
Authorization: Bearer <user_or_service_token>

Response 200

{
  "data": [
    {
      "id": "user_2abc...",
      "email": "alex@example.com",
      "first_name": "Alex",
      "last_name": "Rivera",
      "role": "owner",
      "image_url": "https://...",
      "joined_at": "2026-01-08T14:00:00.000Z"
    },
    {
      "id": "user_2def...",
      "email": "sam@example.com",
      "first_name": "Sam",
      "last_name": "Lee",
      "role": "member",
      "image_url": null,
      "joined_at": "2026-03-01T09:12:00.000Z"
    }
  ]
}

List monitors

GET /v1/organizations/:org_id/monitors
Authorization: Bearer <user_or_service_token>

Returns monitors in the organization (metadata only — not time series). API secrets are not included.

Response 200

{
  "data": [
    {
      "id": "mon_1736...",
      "name": "Warehouse roof",
      "starlink_id": "ut01000000-00000000-00000001",
      "status": "online",
      "created_at": "2026-01-08T14:00:00.000Z",
      "first_data_at": "2026-01-08T15:22:11.000Z"
    }
  ]
}

Add member

POST /v1/organizations/:org_id/members
Authorization: Bearer <user_or_service_token>
Content-Type: application/json

{
  "email": "sam@example.com",
  "role": "member"
}

Or { "userId": "user_…", "role": "admin" }. The target user must already have an Orbimon account and must not belong to another organization. Role must be member or admin (not owner).

Adding a member fails when the organization is at its seat limit. Pending invitations count toward that limit.

Errors

Change member role

PATCH /v1/organizations/:org_id/members/:user_id
Authorization: Bearer <user_or_service_token>
Content-Type: application/json

{
  "role": "admin"
}

Role must be member or admin. Cannot change your own role or demote/remove the last owner via this endpoint.

Remove member

DELETE /v1/organizations/:org_id/members/:user_id
Authorization: Bearer <user_or_service_token>

Cannot remove yourself. Cannot remove the last owner.

Coming later

• Billing endpoints
• Organization-wide metrics rollup (use per-monitor metrics today)
• Public invite-by-email for users who have not signed up yet

See also

• Monitors API
• API overview