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

# Manage team members

> Add, list, update, and remove team members through the Cal ID API.

Use the Cal ID API to manage who belongs to a team and what they can do. Every request is authenticated with a Bearer token, and you must use a **team owner or admin API key** to manage that team's memberships.

All requests go to the base URL `https://api.cal.id` and include an `Authorization: Bearer calid_xxxxx` header. Successful responses return the standard envelope: `{ "success": true, "data": ..., "message": "...", "meta": {...} }`.

A team is identified by a `teamId`, and each membership within it is identified by a `membershipId`.

<Note>
  Team members can hold one of three roles:

  * **MEMBER** — the default role for a newly added member.
  * **ADMIN** — can manage the team and its members.
  * **OWNER** — full control over the team.
</Note>

<Steps>
  <Step title="Add a member">
    Add a user to the team by their `userId`. The `role` field is optional and defaults to `MEMBER`.

    ```bash theme={null}
    curl -X POST "https://api.cal.id/teams/\{teamId\}/memberships" \
      -H "Authorization: Bearer calid_xxxxx" \
      -H "Content-Type: application/json" \
      -d '{"userId":321,"role":"MEMBER"}'
    ```

    ```json theme={null}
    {
      "userId": 321,
      "role": "MEMBER"
    }
    ```
  </Step>

  <Step title="List members">
    Retrieve all memberships for the team. Results are paginated, with pagination details returned in `meta`.

    ```bash theme={null}
    curl -X GET "https://api.cal.id/teams/\{teamId\}/memberships" \
      -H "Authorization: Bearer calid_xxxxx"
    ```
  </Step>

  <Step title="Change a role">
    Update a member's role by their `membershipId`. For example, promote a member to `ADMIN`.

    ```bash theme={null}
    curl -X PATCH "https://api.cal.id/teams/\{teamId\}/memberships/\{membershipId\}" \
      -H "Authorization: Bearer calid_xxxxx" \
      -H "Content-Type: application/json" \
      -d '{"role":"ADMIN"}'
    ```

    ```json theme={null}
    {
      "role": "ADMIN"
    }
    ```
  </Step>

  <Step title="Remove a member">
    Remove a member from the team by their `membershipId`.

    ```bash theme={null}
    curl -X DELETE "https://api.cal.id/teams/\{teamId\}/memberships/\{membershipId\}" \
      -H "Authorization: Bearer calid_xxxxx"
    ```
  </Step>
</Steps>

## Related endpoints

* [Add a team member](/docs/api-reference/team-memberships/add-a-team-member)
* [List team members](/docs/api-reference/team-memberships/list-team-members)
* [Update a team member](/docs/api-reference/team-memberships/update-a-team-member)


## Related topics

- [How to Remove a Member from the Team](/docs/teams/remove-member.md)
- [Inviting Members to an Existing Team](/docs/teams/invite-members.md)
- [Add a team member](/docs/api-reference/team-memberships/add-a-team-member.md)
- [Get a team member](/docs/api-reference/team-memberships/get-a-team-member.md)
- [List team members](/docs/api-reference/team-memberships/list-team-members.md)