Skip to content

Add a user to a team

POST
/teams/{id}/members

Adds an account to a team’s direct members.

You need to be signed in with teams.admin or system.admin granted globally; a grant within the team isn’t enough. A body that can’t be read as JSON, including a user_ref that isn’t a whole number in range, or an id that isn’t a UUID, gets a plain-text 400 before sign-in is checked.

The team must exist, but a deleted one is accepted; an id with no team gets 404. The account isn’t checked: any whole number is stored, including one that matches no account, zero or a negative number, and a user_ref that’s missing or null is stored as 0.

Adding someone who’s already a member succeeds and changes nothing, so the first added_at and adder stay. Membership counts toward opening the team’s team-only content and filing work under the team, both checked fresh on each request; it adds no role or grant, and teams above or below aren’t affected. Nobody is notified, and no audit entry is recorded. Server errors get a plain-text 500.

id
required
string format: uuid

The team’s id.

object
user_ref
required

The account ref to add. It is stored as sent; missing or null counts as 0.

integer format: int64

The account is a member now, whether it was added or already was.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed