Reference

Team and roles

An account can have as many people on it as you like, each with a role that decides what they may do. Roles are about people, not about keys — and the difference matters more than it looks, so it is worth two minutes.

The four roles

Role	Can do	Cannot do
`owner`	Everything, including billing and removing other people.	Be removed, if they are the last one. An account with no owner has nobody who can administer it.
`admin`	Invite, change roles, remove people, manage domains and keys.	Promote anybody to owner, or remove an owner.
`member`	Send mail, manage domains, read the logs — the everyday work.	Touch billing, membership or credentials.
`viewer`	Read messages, domains and statistics.	Send anything, or change anything.

Some things an API key can never do

Inviting somebody, changing a role, removing a colleague, minting a key, and everything to do with billing require a signed-in person. There is no scope that grants them, and adding one to a key will not help.

That is deliberate. These are the actions where a leaked server-side credential stops being an incident and becomes a takeover: a key that could mint keys and change membership would let anybody who found it in a log lock you out of your own account. A key can send your mail; it cannot decide who else may.

Listing the team

GET/v1/teamteam:read

GET /v1/team
# Needs a key with team:read, or a signed-in session.

{
  "data": [
    { "id": "usr_AZLm…", "email": "[email protected]",
      "role": "owner",  "status": "active" },
    { "id": "usr_BQpk…", "email": "[email protected]",
      "role": "member", "status": "invited" }
  ]
}

status is active for somebody who has accepted, and invited for somebody who has been sent an invitation and has not used it yet.

Inviting somebody

POST/v1/team/invitesdashboard session only

Field	Type	Notes
email	string required	Where the invitation is sent.
role	string required	`owner`, `admin`, `member` or `viewer`. There is no default.

POST /v1/team/invites
{ "email": "[email protected]", "role": "member" }

# There is no default role. Choosing one for you is how somebody
# ends up with more access than anybody decided to give them.

They receive an email with a single-use link. Following it sets their password and verifies the address — it does not sign them in, so they choose a password and then log in with it like anybody else.

The link is spent once used, and expires. If somebody comes back to a dead link there is no self-serve resend, by design: an invitation that can be replayed is a way in for whoever else has seen the mailbox. Ask an owner or admin to invite them again.

Changing a role, and removing somebody

PATCH/v1/team/:iddashboard session only

DELETE/v1/team/:iddashboard session only

Changing somebody’s role signs them out everywhere. Their permissions just changed, and a session minted under the old ones would keep working until it expired otherwise.

Removing the last owner is refused. So is promoting somebody to owner unless you are one.

NextAuthentication →How to get an API key, what the scopes allow, and why there is no test environment.