Organizations

Manage organizations, members, invitations, and billing. Organizations are the top-level entity for multi-tenancy, grouping users, projects, and resources under a shared namespace.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Organization Object

{
  "id": "org_xyz",
  "name": "Acme Corp",
  "description": "AI research and development organization",
  "status": "active",
  "plan": "enterprise",
  "memberCount": 25,
  "credits": {
    "balance": 4500.00,
    "currency": "USD"
  },
  "ownerId": "user_456",
  "namespace": "acme-corp",
  "settings": {
    "defaultRole": "member",
    "allowSelfSignup": false,
    "ssoEnabled": true
  },
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

Member Object

{
  "userId": "user_789",
  "role": "member",
  "email": "bob@example.com",
  "name": "Bob Johnson",
  "joinedAt": "2024-08-20T14:00:00Z",
  "isOwner": false
}

Invitation Object

{
  "id": "inv_abc001",
  "email": "newmember@example.com",
  "role": "member",
  "status": "pending",
  "invitedBy": "user_456",
  "expiresAt": "2025-02-15T00:00:00Z",
  "organizationId": "org_xyz",
  "createdAt": "2025-02-01T14:22:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/organizations

List organizations accessible to the authenticated user.

Scope: organizations:read

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: active, suspended, archived
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)

Response 200 OK

{
  "count": 2,
  "limit": 20,
  "offset": 0,
  "organizations": [
    {
      "id": "org_xyz",
      "name": "Acme Corp",
      "description": "AI research and development organization",
      "status": "active",
      "plan": "enterprise",
      "memberCount": 25,
      "ownerId": "user_456",
      "namespace": "acme-corp",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ]
}

---

GET /api/v1/organizations/:id

Get a single organization by ID.

Scope: organizations:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Response 200 OK

Returns the full Organization object.

---

PUT /api/v1/organizations/:id

Update an organization's details.

Scope: organizations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Request Body

{
  "name": "Acme Corporation",
  "description": "Updated description",
  "settings": {
    "defaultRole": "member",
    "allowSelfSignup": true
  }
}

Field	Type	Required	Description
name	string	No	Organization name
description	string	No	Organization description
settings	object	No	Organization settings

Response 200 OK

Returns the updated Organization object.

---

GET /api/v1/organizations/:id/members

List all members of an organization.

Scope: organizations:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Response 200 OK

{
  "organizationId": "org_xyz",
  "members": [
    {
      "userId": "user_456",
      "role": "owner",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "joinedAt": "2024-01-10T08:00:00Z",
      "isOwner": true
    },
    {
      "userId": "user_789",
      "role": "member",
      "email": "bob@example.com",
      "name": "Bob Johnson",
      "joinedAt": "2024-08-20T14:00:00Z",
      "isOwner": false
    }
  ]
}

---

POST /api/v1/organizations/:id/members

Add an existing user as a member to the organization.

Scope: organizations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Request Body

{
  "userId": "user_new001",
  "role": "member"
}

Field	Type	Required	Description
userId	string	Yes	ID of the user to add
role	string	No	Member role: member, admin, billing (default: member)

Response 201 Created

{
  "message": "Member added successfully",
  "organizationId": "org_xyz",
  "userId": "user_new001",
  "role": "member"
}

---

DELETE /api/v1/organizations/:id/members/:userId

Remove a member from the organization. The organization owner cannot be removed.

Scope: organizations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID
userId	string	Yes	User ID of the member to remove

Response 204 No Content

---

PUT /api/v1/organizations/:id/members/:userId

Update a member's role within the organization.

Scope: organizations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID
userId	string	Yes	User ID of the member

Request Body

{
  "role": "admin"
}

Field	Type	Required	Description
role	string	Yes	New role: member, admin, billing

Response 200 OK

{
  "message": "Member role updated",
  "organizationId": "org_xyz",
  "userId": "user_789",
  "role": "admin"
}

---

POST /api/v1/organizations/:id/invite

Send an invitation to join the organization via email.

Scope: organizations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Request Body

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

Field	Type	Required	Description
email	string	Yes	Email address to invite
role	string	Yes	Role to assign upon acceptance: member, admin, billing

Response 201 Created

{
  "invitationId": "inv_abc001"
}

---

GET /api/v1/organizations/:id/invitations

List all pending and recent invitations for the organization.

Scope: organizations:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Response 200 OK

{
  "organizationId": "org_xyz",
  "invitations": [
    {
      "id": "inv_abc001",
      "email": "newmember@example.com",
      "role": "member",
      "status": "pending",
      "invitedBy": "user_456",
      "expiresAt": "2025-02-15T00:00:00Z",
      "organizationId": "org_xyz",
      "createdAt": "2025-02-01T14:22:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ]
}

---

DELETE /api/v1/organizations/:id/invitations/:inviteId

Cancel a pending invitation.

Scope: organizations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID
inviteId	string	Yes	Invitation ID

Response 204 No Content

---

GET /api/v1/organizations/:id/credits

Get the current credit balance and usage summary for the organization.

Scope: organizations:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Response 200 OK

{
  "balance": 4500.00,
  "totalUsed": 1500.00,
  "totalPurchased": 6000.00,
  "currency": "USD"
}

---

GET /api/v1/organizations/:id/transactions

List credit transactions for the organization.

Scope: organizations:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Organization ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of results to return (default: 20)

Response 200 OK

{
  "organizationId": "org_xyz",
  "transactions": [
    {
      "id": "txn_001",
      "type": "debit",
      "amount": 12.50,
      "currency": "USD",
      "description": "Workflow execution: Daily ETL Pipeline",
      "resourceType": "workflow",
      "resourceId": "wf_abc123",
      "userId": "user_456",
      "balanceAfter": 4500.00,
      "createdAt": "2025-02-01T14:22:00Z"
    },
    {
      "id": "txn_002",
      "type": "credit",
      "amount": 1000.00,
      "currency": "USD",
      "description": "Credit purchase",
      "resourceType": "billing",
      "resourceId": null,
      "userId": "user_456",
      "balanceAfter": 4512.50,
      "createdAt": "2025-01-28T10:00:00Z"
    }
  ]
}