Skip to main content

Organization API

This document describes all organization management endpoints. All endpoints require authentication.

Organization Management​

List Organizations​

Retrieves all organizations the authenticated user belongs to.

Endpoint: POST /api/v1/organizations/list

Request Body: None

Success Response: 200 OK

[
  {
    "organizationId": "org_01K3BK4YS5SDH22RV4P9QYJR7Z",
    "organizationName": "ORG321",
    "userRole": "admin"
  },
  {
    "organizationId": "org_01K2Z1R2MEJK6B41WW7428G9YC",
    "organizationName": "ORG123",
    "userRole": "member"
  }
]

Create Organization​

Creates a new organization.

Endpoint: POST /api/v1/organizations/create

Request Body:

{
  "name": "My New Awesome Org"
}

Success Response: 200 OK

{
  "id": "org_01K3921VVZ006Y89KT0DT554KP",
  "organizationName": "My New Awesome Org",
  "domains": []
}

Update Organization​

Updates an existing organization.

Endpoint: POST /api/v1/organizations/update

Request Body:

{
  "organizationId": "org_01K2Z1R2MEJK6B41WW7428G9YC",
  "name": "New ACME Inc. Name"
}

Success Response: 200 OK

{
  "id": "org_01K2Z1R2MEJK6B41WW7428G9YC",
  "organizationName": "New ACME Inc. Name",
  "domains": []
}

Delete Organization​

Deletes an organization.

Endpoint: POST /api/v1/organizations/delete

Request Body:

{
  "organizationId": "org_123123123"
}

Success Response: 200 OK

Invitation Management​

Send Invitation​

Invites a new member to the organization.

Endpoint: POST /api/v1/organizations/send-invitation

Request Body:

{
  "email": "new-teammate@example.com",
  "role": "admin"
}

Parameters:

  • email (required): The email address of the invitee.
  • role (optional): The role slug (e.g., "admin", "member"). Defaults to "member" if omitted

Success Response: 200 OK

List Invitations​

Retrieves a paginated list of organization invitations.

Endpoint: POST /api/v1/organizations/list-invitation

Request Body:

{
  "email": "johndoe@gmail.com",
  "organizationId": "org_123123123",
  "limit": "7",
  "before": "cursor_string",
  "after": "cursor_string"
}

Parameters: All fields are optional. Invitations can be filtered by any combination of criteria.

  • email: Filter by email address
  • organizationId: Organization ID
  • limit: Number of results per page (default 10)
  • before: Cursor for previous page
  • after: Cursor for next page

Success Response: 200 OK

{
  "data": [
    {
      "id": "invitation_01K4SV508PN8CFZF20W3JWXMT8",
      "email": "new-teammate@example.com",
      "state": "pending",
      "acceptedAt": "2024-10-19T10:00:00Z",
      "revokedAt": null,
      "token": "1231241243123412",
      "acceptInvitationUrl": "https://example.com/accept/...",
      "organizationId": "org_01K2Z1R2MEJK6B41WW7428G9YC",
      "inviterUserId": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
      "expiresAt": "2024-10-26T10:00:00Z",
      "createdAt": "2024-10-19T10:00:00Z",
      "updatedAt": "2024-10-19T10:00:00Z"
    }
  ],
  "before": "cursor_string_for_prev_page",
  "after": "cursor_string_for_next_page"
}

Revoke Invitation​

Revokes an existing organization invitation.

Endpoint: POST /api/v1/organizations/revoke-invitation

Request Body:

{
  "invitationId": "invitation_01K4SV508PN8CFZF20W3JWXMT8"
}

Success Response: 200 OK

{
  "id": "invitation_01K4SV508PN8CFZF20W3JWXMT8",
  "email": "new-teammate@example.com",
  "state": "revoked",
  "acceptedAt": "2024-10-19T10:00:00Z",
  "revokedAt": "2024-10-19T10:00:00Z",
  "token": "1231241243123412",
  "acceptInvitationUrl": "https://example.com/accept/...",
  "organizationId": "org_01K2Z1R2MEJK6B41WW7428G9YC",
  "inviterUserId": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
  "expiresAt": "2024-10-26T10:00:00Z",
  "createdAt": "2024-10-19T10:00:00Z",
  "updatedAt": "2024-10-19T10:00:00Z"
}