---
title: "Create a user"
method: POST
path: "/users"
tags: ["Users"]
---

# Create a user

`POST /users`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/users`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Creates a user.
            
Provider decides where the user is created. When omitted, Default is used.
- Default (the service's default identity provider for new users)
- Auth0
            
InitialPassword decides how the user gets their first password. When omitted, a missing
password means Invitation (the identity provider emails the user the way to set their own)
and a supplied password is Permanent. Temporary must be changed at first sign-in. Nothing
is emailed for Permanent or Temporary - the caller delivers the password.
            
To add an invited person, accept their invitation instead; creating the login here registers them without it.

## Request body

- UserDto
  - `provider` string: Where the user is created: Default or Auth0. When omitted: Default.
  - `email` string, required: Email address of the user.
  - `password` string, nullable: Password for the user. Password must include atleast one lowercase character, uppercase character, numeric character as well as a special character.
  - `expireAfterDays` integer, nullable: Expire after the specified days. Must be left blank for users that do not expire.
  - `isInternal` boolean: Creates the user as an internal user. Internal users are excluded from billing and license counts. Use this option for testing, background services, or other non-customer-facing purposes.
  - `bypassMfa` boolean: Bypasses multi-factor authentication for the user. When enabled, the user will not be prompted for two factor authentication during login.
  - `initialPassword` string, nullable: How the user gets their first password: Permanent (the supplied password is final), Temporary (the supplied password must be changed at first sign-in) or Invitation (the user is emailed the way to set their own; any supplied password is ignored). Permanent and Temporary require a password; nothing is emailed for them, the caller delivers the password. When omitted: Invitation if no password is supplied, otherwise Permanent.
  - `mfaEnrollmentGraceDays` integer, nullable: Number of days after creation during which the user may sign in without setting up multi-factor authentication. Once the period ends, enrolment is required at the next sign-in. Between 1 and 90. Auth0 users only; ignored for other providers. When omitted: enrolment is required at the first sign-in.

## Response `200`

When the user was created. Returns the created 'User' object.

- User
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable
  - `self` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `userId` string, nullable: Unique identifier of the user.
  - `email` string, nullable: Email address of the user.
  - `isInternal` boolean: Returns true if the user is flagged as an internal user.
  - `bypassMfa` boolean: Returns true if multi-factor authentication is bypassed for the user.

## Other responses

- `400`: When user or password validation fails, or the requested provider is unknown or not available.

## Changes

- **2026-10-15** `77592e907e3d`: 3 info
  - added the new optional request property `allOf[#/components/schemas/UserDto]/mfaEnrollmentGraceDays` (media type: application/json-patch+json)
  - added the new optional request property `allOf[#/components/schemas/UserDto]/mfaEnrollmentGraceDays` (media type: application/json)
  - added the new optional request property `allOf[#/components/schemas/UserDto]/mfaEnrollmentGraceDays` (media type: application/*+json)
- **2026-09-15** `b05b7b93cefa`: 1 breaking, 7 info
  - removed the success response with the status `202`
  - added the new optional request property `allOf[#/components/schemas/UserDto]/initialPassword` (media type: application/json-patch+json)
  - added the new optional request property `allOf[#/components/schemas/UserDto]/initialPassword` (media type: application/json)
  - added the new optional request property `allOf[#/components/schemas/UserDto]/initialPassword` (media type: application/*+json)
  - …4 more

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/users/post.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)