---
title: "Invite user"
method: POST
path: "/v1/users/invite"
tags: ["users"]
---

# Invite user

`POST /v1/users/invite`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/users/invite`
- Auth: HTTP bearer

Creates a new person in the workspace, or reuses an existing one, and assigns them a role at the chosen locations. A new person gets an email with a link to set their password. When a signed-in user sends the invite, the email goes out only when that user's own email address is verified. An invite made with an API key sends the email in the workspace's name. You cannot grant a role carrying permissions you do not hold yourself.

**Notes.**
- Answers 200 (not 201) for a new person too; `created` tells the two apart.
- For a signed-in user, the set-password email is sent only when that user's own email address is verified. An invite made with an API key sends the email too, from the workspace (the key's name is not shown). The 30-a-minute limit counts per key for a key.

## Request body

- object
  - `email` string, required: Stored in lower case.
  - `name` string: Used only when the person is new.
  - `roleId` string, required
  - `nodeIds` string[], required: Locations to grant the role at. You need `user.edit` and every permission of the role at each one.

## Response `200`

Success.

- object
  - `data` object, required
    - `id` string, required
    - `email` string, required
    - `status` 'active' | 'invited' | 'deactivated', required
    - `created` boolean, required: True when a new person was created; false when an existing person got the extra access.
    - `emailSent` boolean, required: A set-password email went out.
    - `emailBlockedReason` 'inviter-unverified' | 'provider-refused', nullable, required: Why no email went out for a new person: the calling user's own email address is not verified (never for an API key), or the mail provider refused it. Null when sent, or when the person already existed.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The role holds permissions you do not hold, or you lack `user.edit` or the role's permissions at one of the locations.
- `404`: No such role or location in this workspace.
- `422`: Invalid `email`, or `roleId` / `nodeIds` missing.
- `429`: More than 30 invites a minute.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)