Lettermint
Team API

Manage member access

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

Code
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.

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

Call listTeamRoles to list the team's reusable roles. Call listTeamMembers to list members and their current assignments. Method names use the normal naming convention for each SDK, such as team.members.updateAssignment in Node.js, team.members.update_assignment in Python and Team.Members.UpdateAssignment in Go.

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

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.

Assign selected projects

selected applies the role's project permissions only to the listed projects. Replace the example IDs with IDs returned by listTeamRoles and listTeamMembers.

import { Lettermint } from "lettermint"; const lettermint = new Lettermint({ teamToken: process.env.LETTERMINT_TEAM_TOKEN!, }); const member = await lettermint.team.members.updateAssignment("user-id", { role_id: "role-id", project_access: { scope: "selected", project_ids: ["project-a-id", "project-b-id"], }, });

A successful request returns the complete member assignment.

Assign all projects

Use "scope": "all" to include every current and future project. Do not include project_ids:

JSONCode
{
  "role_id": "role-id",
  "project_access": {
    "scope": "all"
  }
}

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

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

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 for complete schemas and response details.

QuickstartTeam API reference