Organization & Users

Organization endpoints

Method	Path	Description	Scope
GET	/api/v1/org	Read org.	admin
PATCH	/api/v1/org	Update org metadata.	admin
GET	/api/v1/org/settings	Read org settings.	admin
PUT	/api/v1/org/settings	Replace org settings.	admin
POST	/api/v1/org/transfer-ownership	Transfer ownership to another user.	admin

Org document

{
  "id": "01HXORG...",
  "slug": "example",
  "name": "Example, Inc.",
  "plan": "pro",
  "seat_count": 23,
  "created_at": "2024-06-01T00:00:00Z"
}

The slug is immutable; it’s the prefix on public URLs (status pages, event-ingest tokens). Contact support to change it.

Settings

Org settings hold broad configuration: notification defaults, retention windows, SSO options, CloudEvents ingest auth. Read the full document with GET /org/settings, replace wholesale with PUT.

User endpoints

Method	Path	Description	Scope
GET	/api/v1/users	List users.	admin
GET	/api/v1/users/{id}	Read a user.	admin
POST	/api/v1/users	Invite a user.	admin
PATCH	/api/v1/users/{id}	Update user (role, status).	admin
DELETE	/api/v1/users/{id}	Remove a user.	admin
POST	/api/v1/users/{id}/reset-password	Trigger a password-reset email.	admin

Invite a user

POST /api/v1/users
{
  "email": "[email protected]",
  "role": "member",
  "team_ids": ["01HXTEAM..."]
}

role	Grants
owner	All admin + billing + destructive org operations. One owner per org.
admin	Manage users, teams, settings, API keys.
member	Standard access. Can manage monitors, alerts, etc. scoped by team membership.
viewer	Read-only across the org.

The invitee receives an email with a link; they set their own password and MFA before first login.

API key endpoints

Method	Path	Description	Scope
GET	/api/v1/org/api-keys	List keys (metadata only; values are never returned after creation).	admin
POST	/api/v1/org/api-keys	Create a key.	admin
DELETE	/api/v1/org/api-keys/{id}	Revoke a key.	admin

Create a key

POST /api/v1/org/api-keys
{
  "name": "CI pipeline",
  "scopes": ["monitors", "alerts"],
  "expires_at": "2027-04-24T00:00:00Z"
}

Response 201 Created:

{
  "id": "key_01HX...",
  "name": "CI pipeline",
  "scopes": ["monitors", "alerts"],
  "prefix": "yy_live_abCd",
  "expires_at": "2027-04-24T00:00:00Z",
  "secret": "yy_live_abCdEfGhIjK..."
}

The full secret is returned once. Store it immediately; after this response it can never be retrieved.

Ownership transfer

POST /api/v1/org/transfer-ownership

{ "new_owner_user_id": "usr_bob" }

The current owner becomes an admin; the named user becomes owner. Requires the caller be the current owner. Irreversible in one call: the new owner must transfer back to undo.

Related resources

• Teams: team management.
• Integrations → API Keys: setup guide and scope reference.