> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/platform-admin/give-people-access/manage-team-membership.md).

# Manage team membership

Add or remove team members, and what a team role does not affect.

`POST /teams/{teamId}/members` adds a member; `DELETE /teams/{teamId}/members/{userId}` removes one. This is the API equivalent of [Manage team membership](https://docs.uptiq.ai/platform-guides/admin/give-people-access/manage-team-membership).

## At a glance

| Item              | Value                                           |
| ----------------- | ----------------------------------------------- |
| ⚙️ Microservice   | `Identity Hub`                                  |
| 🌍 Environment    | `QA`                                            |
| 🔗 Base URL       | `https://api-builder-qa.uptiq.dev/identity-hub` |
| ⌘ Add endpoint    | `POST /teams/{teamId}/members`                  |
| ⌘ Remove endpoint | `DELETE /teams/{teamId}/members/{userId}`       |

{% columns %}
{% column %}

#### What it does

Adds an existing account user to a team or soft-removes their membership.
{% endcolumn %}

{% column %}

#### Success looks like

The service returns a membership record with `Active` or `Removed` status.
{% endcolumn %}
{% endcolumns %}

## Before you start

* Your API key needs the **Manage teams** and **View user** capabilities (`ManageTeam`, `ViewUser`).
* The person must already have a user record in the account — this call adds an existing member, it doesn't invite a new one. See [Invite a user](/cookbooks/platform-admin/give-people-access/invite-someone.md) first if they don't.

## Add a member

`POST /teams/{teamId}/members`

| Field      | Type   | Required | What it does                                            |
| ---------- | ------ | -------- | ------------------------------------------------------- |
| `userId`   | string | Yes      | The account member to add.                              |
| `teamRole` | string | No       | `admin` or `member`. Defaults to `member`.              |
| `status`   | string | No       | `Invited`, `Active`, `InvitationRevoked`, or `Removed`. |

## Code snippets

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api-builder-qa.uptiq.dev/identity-hub/teams/TEAM_ID/members \
  -H "x-platform-key: YOUR_API_KEY" \
  -H "accountid: YOUR_ACCOUNT_ID" \
  -H "content-type: application/json" \
  -d '{ "userId": "USER_ID", "teamRole": "member" }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`https://api-builder-qa.uptiq.dev/identity-hub/teams/${teamId}/members`, {
  method: "POST",
  headers: {
    "x-platform-key": process.env.UPTIQ_API_KEY,
    accountid: process.env.UPTIQ_ACCOUNT_ID,
    "content-type": "application/json",
  },
  body: JSON.stringify({ userId, teamRole: "member" }),
});
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

requests.post(
    f"https://api-builder-qa.uptiq.dev/identity-hub/teams/{team_id}/members",
    headers={
        "x-platform-key": os.environ["UPTIQ_API_KEY"],
        "accountid": os.environ["UPTIQ_ACCOUNT_ID"],
    },
    json={"userId": user_id, "teamRole": "member"},
)
```

{% endtab %}
{% endtabs %}

## Remove a member

`DELETE /teams/{teamId}/members/{userId}` — no body. A soft remove; the audit record of former membership isn't destroyed.

```bash
curl -X DELETE https://api-builder-qa.uptiq.dev/identity-hub/teams/TEAM_ID/members/USER_ID \
  -H "x-platform-key: YOUR_API_KEY" \
  -H "accountid: YOUR_ACCOUNT_ID"
```

## Response

| Result          | What it means                                                                                   | Next action                                        |
| --------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| ✅ `201 Created` | The service adds the member and returns a membership record with `status` set to `Active`.      | Store the membership ID if you need it.            |
| ✅ `200 OK`      | The service soft-removes the member and returns the same record with `status` set to `Removed`. | The former membership remains in the audit record. |

{% hint style="success" %}
**Verified against QA on 22 September 2026.** Field names and nesting below are exactly as returned; identifiers and personal data are placeholders.
{% endhint %}

```json
{
  "message": "Member added successfully",
  "data": {
    "id": "ea29e882-a8cc-4eaa-8d04-9dba102fb770",
    "userId": "571781cc-f16d-4652-9042-3ef90e82efc4",
    "teamId": 11,
    "accountId": "YOUR_ACCOUNT_ID",
    "teamRole": "member",
    "status": "Active",
    "createdAt": "2026-09-22T14:32:08.166Z",
    "createdBy": "system",
    "updatedAt": "2026-09-22T14:32:08.166Z",
    "updatedBy": "system"
  }
}
```

After `DELETE /teams/{teamId}/members/{userId}`, the same record returns with `"status": "Removed"`, `"message": "Member removed successfully"` and `updatedBy` set to `null`. `data.id` is the **membership** id, distinct from both `userId` and `teamId`.

## Developer notes

| Situation                 | What to do                                                                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Choose `teamRole`         | Use `admin` or `member` for the person's team role. It is separate from their account-wide [role](/cookbooks/platform-admin/give-people-access/change-someones-access.md).           |
| Interpret `data.id`       | Treat it as the membership ID. It differs from both `userId` and `teamId`.                                                                                                           |
| Revoke all account access | Removing a member doesn't change account membership. Use [Remove a user's access](/cookbooks/platform-admin/give-people-access/remove-someones-access.md) to revoke access entirely. |

## Related

* [Manage team membership](https://docs.uptiq.ai/platform-guides/admin/give-people-access/manage-team-membership) — as a screen
* [Create a team](/cookbooks/platform-admin/give-people-access/create-a-team.md)
* [Remove a user's access](/cookbooks/platform-admin/give-people-access/remove-someones-access.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/cookbooks/platform-admin/give-people-access/manage-team-membership.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.