---
title: "Team API"
description: "Team in the OneSend API: 13 endpoints. Workspace members, roles (owner, admin, member, viewer) and invitations."
url: https://onesend.email/docs/api-reference/team/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Team

Workspace members, roles (owner, admin, member, viewer) and invitations.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## Look up an invitation

POST `/v1/auth/invitation`

For the accept page: workspace, role and whether the invited email already has an account.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `token`required | `string` |  |

### Responses

`200` Success

```
{
  "workspace": {
    "id": string,
    "name": string
  },
  "email": string,
  "role": string,
  "roleLabel": string,
  "invitedBy": {
    "email": string,
    "name": string or null
  },
  "expiresAt": string,
  "accountExists": boolean,
  "signedInAs": string or null,
  "alreadyMember": boolean
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Accept an invitation

POST `/v1/auth/invitation/accept`

Signed in as the invited email: joins the workspace and switches this session to it. Not signed in and no account for the email: send `password` (and `name`) to create the account and join; this works whatever ONESEND\_SIGNUP says, because the invitation is the permission. An account exists but you are not signed in: 401 `login_required`.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `token`required | `string` |  |
| `name` | `string` |  |
| `password` | `string` | Only when creating a new account |

### Responses

`200` Success

```
{
  "token": string,
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  }
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## List workspace members

GET `/v1/team/members`

Every role can list members.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "userId": string,
    "email": string,
    "name": string or null,
    "role": "viewer" | "member" | "admin" | "owner",
    "joinedAt": string,
    "twoFactorEnabled": boolean,
    "you": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Change a member's role

PATCH `/v1/team/members/{userId}`

Admins and the owner. Roles: `admin`, `member`, `viewer`. The owner's role cannot be changed (transfer ownership instead), and nobody changes their own role.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `userId`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `role`required | `"admin" \| "member" \| "viewer"` |  |

### Responses

`200` Success

```
{
  "userId": string,
  "email": string,
  "name": string or null,
  "role": "viewer" | "member" | "admin" | "owner",
  "joinedAt": string,
  "twoFactorEnabled": boolean,
  "you": boolean
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Remove a member

DELETE `/v1/team/members/{userId}`

Admins and the owner. The owner cannot be removed. Their sessions stop working in this workspace at once. To leave a workspace yourself, use POST /v1/team/leave.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `userId`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Leave the current workspace

POST `/v1/team/leave`

Any role except the owner (transfer ownership first). You cannot leave your only workspace.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Transfer ownership to another member

POST `/v1/team/transfer-ownership`

Owner only, in a dashboard session. Confirm with your password (and two-factor code if it is on). You become an admin.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `userId`required | `string` |  |
| `password`required | `string` | Your current password, to confirm. |
| `code` | `string` | Two-factor code, when two-factor authentication is on for your account. |

### Responses

`200` Success

```
{
  "data": [{
    "userId": string,
    "email": string,
    "name": string or null,
    "role": "viewer" | "member" | "admin" | "owner",
    "joinedAt": string,
    "twoFactorEnabled": boolean,
    "you": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## List invitations

GET `/v1/team/invitations`

Admins and the owner. Pending invitations by default; `status=all` includes accepted, revoked and expired ones.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `status` | query | `"pending" \| "all"` |  |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "invitation",
    "email": string,
    "role": "admin" | "member" | "viewer",
    "status": "pending" | "accepted" | "revoked" | "expired",
    "invitedBy": {
      "email": string,
      "name": string or null
    },
    "expiresAt": string,
    "lastSentAt": string or null,
    "sendCount": number,
    "createdAt": string
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Invite someone by email

POST `/v1/team/invitations`

Admins and the owner. Sends an invitation email through this workspace's router (a system email). The link works for 7 days. Inviting an address that already has a pending invitation sends a new link and updates the role. When the email cannot be delivered (only the Sandbox), `link` returns the invitation link to a signed-in admin to pass on; never to an API key (an API key cannot invite someone without the email reaching them). An invitation sent with an API key is tied to it: when the key is revoked or reported as leaked (or a key that created it is), the invitation is canceled, and a member who joined through it is removed from the workspace (their API keys, inbox rules, forwarding and connected mailboxes stop too). Sending it again from the dashboard unties it.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |
| `role` | `"admin" \| "member" \| "viewer"` | Default "member". |

### Responses

`201` Success

```
{
  "id": string,
  "object": "invitation",
  "email": string,
  "role": "admin" | "member" | "viewer",
  "status": "pending" | "accepted" | "revoked" | "expired",
  "invitedBy": {
    "email": string,
    "name": string or null
  },
  "expiresAt": string,
  "lastSentAt": string or null,
  "sendCount": number,
  "createdAt": string,
  "emailDelivery": boolean,
  "link": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Resend an invitation

POST `/v1/team/invitations/{id}/resend`

Sends a new link (the previous link stops working) and restarts the 7 days.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "invitation",
  "email": string,
  "role": "admin" | "member" | "viewer",
  "status": "pending" | "accepted" | "revoked" | "expired",
  "invitedBy": {
    "email": string,
    "name": string or null
  },
  "expiresAt": string,
  "lastSentAt": string or null,
  "sendCount": number,
  "createdAt": string,
  "emailDelivery": boolean,
  "link": string
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Revoke an invitation

DELETE `/v1/team/invitations/{id}`

The link stops working at once.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Team security settings

GET `/v1/team/settings`

Whether two-factor authentication is required, whether the workspace can deliver system email, and the role permission matrix.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "require2fa": boolean,
  "emailDelivery": boolean,
  "membersWithout2fa": number,
  "roles": [{
    "area": string,
    "viewer": boolean,
    "member": boolean,
    "admin": boolean,
    "owner": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Require two-factor authentication

PATCH `/v1/team/settings`

Admins and the owner. With `require2fa`, members without two-factor authentication can only manage their own account until they turn it on and sign in again. Turn it on for your own account first.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `require2fa`required | `boolean` |  |

### Responses

`200` Success

```
{
  "require2fa": boolean,
  "emailDelivery": boolean,
  "membersWithout2fa": number,
  "roles": [{
    "area": string,
    "viewer": boolean,
    "member": boolean,
    "admin": boolean,
    "owner": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
