Team API

These endpoints manage organization membership, roles, and invitations.

Roles

Role	Description
owner	Full admin rights. Created automatically for the organization founder.
admin	Administrative role. Same permissions as owner with behavioral constraints (cannot self-promote, cannot remove owners).
developer	Can create, deploy, and run projects.
reader	Read-only access to projects and data.

---

GET /api/v1/organizations/members

Returns all members in your organization. Requires authentication but not a specific role.

Response

{
  "members": [
    {
      "id": "user_abc123",
      "organization_id": "org-xxxxxxxx",
      "email": "alice@acme.com",
      "name": "Alice Smith",
      "picture": "https://cdn.example.com/avatar.png",
      "role": "owner",
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-01-10T09:00:00Z",
      "last_login_at": "2026-04-27T14:30:00Z"
    }
  ],
  "total": 4
}

---

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

Updates a member's role. Requires the manage_team permission (admin or owner).

• Only owners can assign the admin or owner role.
• Admins can only assign developer or reader.
• You cannot change your own role.
• You cannot demote the last owner.

Path Parameters

Parameter	Type	Description
userId	string	User ID of the member to update

Request Body

{
  "role": "developer"
}

Field	Type	Required	Values
role	string	yes	"owner", "admin", "developer", "reader"

Response

{
  "member": {
    "id": "user_abc123",
    "role": "developer",
    ...
  },
  "message": "Member role updated successfully"
}

---

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

Removes a member from the organization. Requires the manage_team permission.

• You cannot remove yourself.
• Only owners can remove admins or other owners.
• You cannot remove the last owner.

Path Parameters

Parameter	Type	Description
userId	string	User ID of the member to remove

Response

{
  "message": "Member removed successfully"
}

---

GET /api/v1/organizations/invitations

Returns all pending invitations for the organization. Requires the manage_team permission.

Response

{
  "invitations": [
    {
      "id": "inv_abc123",
      "organization_id": "org-xxxxxxxx",
      "email": "bob@acme.com",
      "role": "developer",
      "invited_by": "user_abc123",
      "expires_at": "2026-05-05T10:00:00Z",
      "created_at": "2026-04-28T10:00:00Z"
    }
  ],
  "total": 1
}

---

POST /api/v1/organizations/invitations

Creates an invitation for a new user to join the organization. Only owners can invite users with the admin role.

Request Body

{
  "email": "bob@acme.com",
  "role": "developer"
}

Field	Type	Required	Description
email	string	yes	Email address of the user to invite
role	string	yes	Role to assign: "admin", "developer", or "reader"

Response

{
  "invitation": {
    "id": "inv_abc123",
    "email": "bob@acme.com",
    "role": "developer",
    "expires_at": "2026-05-05T10:00:00Z",
    "token": "..."
  },
  "message": "Invitation created successfully"
}

Token delivery

The invitation token is returned in the response. In production, send this token to the invitee via email. The token is used with the POST /api/v1/invitations/accept endpoint.

---

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

Cancels a pending invitation.

Path Parameters

Parameter	Type	Description
id	string	Invitation ID

Response

{
  "message": "Invitation cancelled successfully"
}