> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Team management API

> Invite team members, list members and pending invitations, change roles, revoke invitations, and remove members via the scaling.cloud API.

Manage your organization's team members programmatically. All team management endpoints require an `org:admin` role.

<Tip>
  Prefer to work in the dashboard? See [Invite Team Members](/guides/invite-team-members) for the UI walkthrough.
</Tip>

<Note>
  scaling.cloud has two roles:

  * **`org:admin`** — Full access to all settings, including inviting and removing members, managing roles, and configuring escalation policies and on-call schedules.
  * **`org:member`** — Can view and manage incidents but cannot access team or organization settings.

  Every organization must have at least one admin.
</Note>

<Steps>
  <Step title="Invite a member">
    Send a `POST` request to `/api/team/members/invite` with the invitee's email address and desired role.

    ```bash theme={null}
    curl -X POST https://api.scaling.cloud/v1/team/members/invite \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "emailAddress": "jane@example.com",
        "role": "org:member"
      }'
    ```

    A successful response returns the invitation:

    ```json theme={null}
    {
      "data": {
        "id": "inv_01jqm5x3k8vz9e2f4g7h",
        "emailAddress": "jane@example.com",
        "role": "org:member",
        "status": "pending",
        "createdAt": "2026-04-07T10:00:00.000Z"
      }
    }
    ```

    The invitee receives an email with a link to accept the invitation and join your organization. The invitation stays in `pending` status until they accept or you revoke it.
  </Step>

  <Step title="List members and pending invitations">
    Send a `GET` request to `/api/team/members` to see all current members and outstanding invitations in a single response.

    ```bash theme={null}
    curl https://api.scaling.cloud/v1/team/members \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "data": {
        "members": [
          {
            "id": "user_01jqm3xy4z5abc6de7fg",
            "email": "alice@example.com",
            "firstName": "Alice",
            "lastName": "Chen",
            "imageUrl": "https://example.com/avatars/alice.jpg",
            "role": "org:admin",
            "joinedAt": "2026-01-15T09:00:00.000Z"
          },
          {
            "id": "user_01jqm4ab2c3de5fg6hij",
            "email": "bob@example.com",
            "firstName": "Bob",
            "lastName": "Martinez",
            "imageUrl": null,
            "role": "org:member",
            "joinedAt": "2026-02-20T14:30:00.000Z"
          }
        ],
        "invitations": [
          {
            "id": "inv_01jqm5x3k8vz9e2f4g7h",
            "emailAddress": "jane@example.com",
            "role": "org:member",
            "status": "pending",
            "createdAt": "2026-04-07T10:00:00.000Z"
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Update a member's role">
    Send a `PATCH` request to `/api/team/members/{userId}/role` to promote or demote a member. Replace `{userId}` with the member's user ID from the list response.

    ```bash theme={null}
    curl -X PATCH https://api.scaling.cloud/v1/team/members/user_01jqm4ab2c3de5fg6hij/role \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "role": "org:admin"
      }'
    ```

    The response confirms the updated role:

    ```json theme={null}
    {
      "data": {
        "id": "user_01jqm4ab2c3de5fg6hij",
        "role": "org:admin"
      }
    }
    ```

    <Warning>
      Admins cannot change their own role or remove themselves from the organization. These actions must be performed by another admin. Attempting to do so returns a `400` error.
    </Warning>
  </Step>

  <Step title="Revoke a pending invitation">
    If you need to cancel an invitation before it's accepted, send a `DELETE` request to `/api/team/members/invitations/{invitationId}`. Replace `{invitationId}` with the ID from the invitation list.

    ```bash theme={null}
    curl -X DELETE https://api.scaling.cloud/v1/team/members/invitations/inv_01jqm5x3k8vz9e2f4g7h \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "data": {
        "success": true
      }
    }
    ```

    The invitation link in the invitee's email will no longer work after revocation.
  </Step>

  <Step title="Remove a member">
    Send a `DELETE` request to `/api/team/members/{userId}` to remove an existing member from your organization. This immediately revokes their access.

    ```bash theme={null}
    curl -X DELETE https://api.scaling.cloud/v1/team/members/user_01jqm4ab2c3de5fg6hij \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "data": {
        "success": true
      }
    }
    ```

    The removed member will lose access to all incidents, schedules, and settings immediately. Their historical activity (such as incident status changes they made) is preserved.
  </Step>
</Steps>