Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zitadel/zitadel/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST /v2/users/new

​
Description

Create a new user or service account in the specified organization. This endpoint supports creating both human users and machine users (service accounts).

​
Required Permission

  • user.write

​
Request Body

​
user
object
required
The user to create. Can be either a human user or a machine user.
​
userId
string
Optional unique identifier for the user. If omitted, the system will generate one.
​
username
string
required
Username for the user. Must be unique within the organization or globally depending on settings.
​
organization
object
Organization context for the user.
​
orgId
string
Organization ID where the user will be created.
​
profile
object
Profile information for human users.
​
givenName
string
required
First name of the user.
​
familyName
string
required
Last name of the user.
​
nickName
string
Nickname of the user.
​
displayName
string
Display name of the user.
​
preferredLanguage
string
Preferred language code (e.g., “en”, “de”).
​
gender
string
Gender of the user. Options: GENDER_FEMALE, GENDER_MALE, GENDER_DIVERSE.
​
email
object
Email configuration for the user.
​
email
string
required
Email address.
​
isVerified
boolean
Whether the email is already verified.
​
phone
object
Phone configuration for the user.
​
phone
string
required
Phone number in E.164 format.
​
isVerified
boolean
Whether the phone is already verified.

​
Response

​
userId
string
The unique identifier of the newly created user.
​
details
object
Metadata about the creation.
​
sequence
string
Sequence number of the change.
​
changeDate
timestamp
Timestamp of when the user was created.
​
resourceOwner
string
Organization ID that owns the user.
​
emailCode
string
Email verification code if email verification was requested and not sent.
​
phoneCode
string
Phone verification code if phone verification was requested and not sent.

​
Example Request

curl -X POST https://your-domain.zitadel.cloud/v2/users/new \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "minnie.mouse",
    "organization": {
      "orgId": "69629026806489455"
    },
    "profile": {
      "givenName": "Minnie",
      "familyName": "Mouse",
      "displayName": "Minnie Mouse",
      "preferredLanguage": "en",
      "gender": "GENDER_FEMALE"
    },
    "email": {
      "email": "minnie@example.com",
      "isVerified": false
    }
  }'

​
Example Response

{
  "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
  "details": {
    "sequence": "1234",
    "changeDate": "2024-03-15T10:30:00Z",
    "resourceOwner": "69629026806489455"
  }
}

​
Error Responses

  • 409 Conflict - User already exists with the same username
  • 400 Bad Request - Invalid request data
  • 403 Forbidden - Insufficient permissions