> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

Use the Users API to manage who has access to a workspace and what they can do. Each member is assigned a role that controls their permissions within that workspace.

***

## List Members

Returns all members of a workspace.

```bash theme={null}
curl https://api.moonshadow.dev/v1/workspaces/ws_abc123/members \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID, e.g. `ws_abc123`.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of member objects.
</ResponseField>

<ResponseField name="data[].user_id" type="string">
  Unique user identifier, e.g. `usr_xyz789`.
</ResponseField>

<ResponseField name="data[].email" type="string">
  Email address of the member.
</ResponseField>

<ResponseField name="data[].role" type="string">
  Role in the workspace: `owner`, `admin`, or `member`.
</ResponseField>

<ResponseField name="data[].joined_at" type="string">
  ISO 8601 timestamp of when the user joined the workspace.
</ResponseField>

```json theme={null}
{
  "data": [
    {
      "user_id": "usr_xyz789",
      "email": "alice@example.com",
      "role": "owner",
      "joined_at": "2024-01-15T10:30:00Z"
    },
    {
      "user_id": "usr_pqr012",
      "email": "bob@example.com",
      "role": "member",
      "joined_at": "2024-02-10T09:00:00Z"
    }
  ]
}
```

***

## Invite a Member

Invites a new user to join a workspace. An invitation email is sent if the user does not already have an account.

```bash theme={null}
curl -X POST https://api.moonshadow.dev/v1/workspaces/ws_abc123/members/invite \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "charlie@example.com",
    "role": "admin"
  }'
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID to invite the member into.
</ParamField>

### Request Body

<ParamField body="email" type="string" required>
  Email address of the person to invite.
</ParamField>

<ParamField body="role" default="member" type="string">
  Role to assign: `owner`, `admin`, or `member`.
</ParamField>

### Response

```json theme={null}
{
  "user_id": "usr_stu345",
  "email": "charlie@example.com",
  "role": "admin",
  "status": "invited",
  "invited_at": "2024-06-10T17:30:00Z"
}
```

***

## Update Member Role

Changes the role of an existing workspace member.

```bash theme={null}
curl -X PATCH https://api.moonshadow.dev/v1/workspaces/ws_abc123/members/usr_stu345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID.
</ParamField>

<ParamField path="userId" type="string" required>
  The user ID of the member to update.
</ParamField>

### Request Body

<ParamField body="role" type="string" required>
  New role for the member: `owner`, `admin`, or `member`.
</ParamField>

### Response

```json theme={null}
{
  "user_id": "usr_stu345",
  "email": "charlie@example.com",
  "role": "member",
  "updated_at": "2024-06-10T18:00:00Z"
}
```

<Note>
  A workspace must always have at least one owner. You cannot change the role of the sole owner.
</Note>

***

## Remove a Member

Removes a member from a workspace.

```bash theme={null}
curl -X DELETE https://api.moonshadow.dev/v1/workspaces/ws_abc123/members/usr_stu345 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID.
</ParamField>

<ParamField path="userId" type="string" required>
  The user ID of the member to remove.
</ParamField>

### Response

Returns `204 No Content` on success.

<Warning>
  Removing a member immediately revokes their access to the workspace and all associated integrations. This action cannot be undone, but you can re-invite the user later.
</Warning>