Skip to main content
POST
Create a user

Authorizations

Authorization
string
header
required

A machine-client token from POST /v1/auth/client-token. Reads need the pulse.read scope; provisioning and tenant updates need pulse.write, which the token only carries when requested_scopes asks for it. Creating, changing, disabling and resetting MFA for users, and the tenant sign-in policy, need a signed-in user's token instead: they reject API-key tokens.

Body

application/json

Creates a user with access to one tenant. The user can sign in straight away with the password you set; no invitation email is sent. Validation failures return 400 with the field names as keys, for example {"email": ["invalid"]}.

tenant_id
string<uuid>
required

The tenant the user gets access to, including every tenant beneath it. Must be your own tenant or one beneath it.

first_name
string
required

The user's first name. Required; at most 100 characters, and at most 200 together with last_name. Otherwise 400 with first_name: ["invalid"].

last_name
null | string
required

The user's last name.

email
string
required

The user's email, which is also their login id. Stored in lower case. An invalid address returns 400 with email: ["invalid"]; an email already used by any user returns 409 email_taken.

password
string
required

The user's password: at least 12 characters, with an upper-case letter, a lower-case letter, a digit and a symbol. Missing returns 400 with password: ["required"]; too weak returns 400 password_rejected.

role
string
required

The user's role: a key from List assignable user roles (GET /v1/msp/admin/user-roles). Admin roles can make changes; reader roles can only view. Any other value returns 400 with role: ["unsupported"].

Response

Created

A user and their access to one tenant.

user_id
string<uuid>
required

The user's id. Use it as userId in the other user endpoints.

first_name
string
required

The user's first name.

last_name
string
required

The user's last name. An empty string when none is set.

display_name
string
required

The user's full name, or their email when no name is set.

email
string
required

The user's email, which is also their login id.

tenant_id
string<uuid>
required

The tenant this access applies to (including the tenants beneath it).

tenant_name
string
required

The name of tenant_id.

roles
string[]
required

The user's role on this tenant: a key from List assignable user roles.

scopes
string[]
required

What the role allows: pulse.login, pulse.read, and pulse.write for admin roles.

status
string
required

active when the user can sign in; disabled when they have been disabled or are locked out.

last_login_at
null | string<date-time>
required

When the user last signed in: an ISO 8601 timestamp in UTC (offset +00:00). Null if they never have.

selected_mfa_method
null | enum<string>
required

The MFA method the user chose: email or totp. Null when none is chosen.

Available options:
email,
totp
enrolled_mfa_methods
enum<string>[]
required

The MFA methods the user has set up: email, totp, both, or none.

Available options:
email,
totp