# Manage member access

Use the Team API to keep a member's Lettermint access in sync with your own provisioning workflow.

```text
Role = what a member can do
Project access = where project permissions apply
```

The API replaces both parts atomically in one request.

## Create an assignment token

Create a Team API token with these abilities:

- `read:members`
- `write:member_assignments`

Only an Owner can add `write:member_assignments` to a token. It is a sensitive ability and is not included in `*`. If the integration otherwise needs full access, select both `*` and `write:member_assignments`.

:::warning
An assignment token can grant any active non-Owner role and any project scope in the team. Store it in a secrets manager, restrict it by IP where possible, and use a dedicated token for this integration.
:::

## Find roles and members

List the team's reusable roles:

```bash title="cURL"
curl -X GET "https://api.lettermint.co/v1/team/roles" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $LETTERMINT_TEAM_TOKEN"
```

The Owner role is included for display. Team API tokens cannot assign or remove Owner; Owners manage those assignments in the dashboard.

Next, list members and their current assignments:

```bash title="cURL"
curl -X GET "https://api.lettermint.co/v1/team/members" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $LETTERMINT_TEAM_TOKEN"
```

The top-level member `id` is the user ID used in member and assignment URLs. Member responses include `name`, `email`, `role: { id, name }`, `project_access`, and `joined_at`. Selected project access is returned as `project_access.projects`, where each project contains its `id` and `name`. An `all` scope includes every current and future project and returns an empty `projects` list.

Before a team has moved to reusable roles, these member and role endpoints return `409 rbac_not_enabled` instead of partial assignment data.

## Assign all projects

`all` includes every current and future project:

```bash title="cURL"
curl -X PUT "https://api.lettermint.co/v1/team/members/USER_ID/assignment" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $LETTERMINT_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "ROLE_ID",
    "project_access": {
      "scope": "all"
    }
  }'
```

## Assign selected projects

`selected` applies the role's project permissions only to the listed projects:

```bash title="cURL"
curl -X PUT "https://api.lettermint.co/v1/team/members/USER_ID/assignment" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $LETTERMINT_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "ROLE_ID",
    "project_access": {
      "scope": "selected",
      "project_ids": ["PROJECT_A_ID", "PROJECT_B_ID"]
    }
  }'
```

Selected access does not include future projects automatically. Send an empty `project_ids` array for a team-only role such as Billing:

```json
{
  "role_id": "BILLING_ROLE_ID",
  "project_access": {
    "scope": "selected",
    "project_ids": []
  }
}
```

A successful update returns the complete member assignment. Owner assignments return `owner_protected`; manage Owners from **Manage team** → **Members**.

## Related endpoints

- `GET /v1/team/roles` lists reusable roles and permission keys.
- `GET /v1/team/members` lists complete assignments.
- `GET /v1/team/members/{userId}` returns one assignment.
- `PUT /v1/team/members/{userId}/assignment` replaces one assignment.

See the [Team API reference](/api-reference/team) for complete schemas and response details.