Skip to main content

Create/Import User (Human)​

Create/import a new user with the type human. The newly created user will get an initialization email if either the email address is not marked as verified or no password is set. If a password is set the user will not be requested to set a new one on the first login.

Header Parameters
    x-zitadel-orgid string

    The default is always the organization of the requesting user. If you like to add users to another organization include the header. Make sure the user has permission in the requested organization.

Request Body required
    userName string required
    profile object required

    Profile includes the basic information of a user, like first name, last name, etc.

    firstName string required

    Possible values: non-empty and <= 200 characters

    lastName string required

    Possible values: non-empty and <= 200 characters

    nickName string

    Possible values: <= 200 characters

    displayName string

    Possible values: <= 200 characters

    preferredLanguage string

    Possible values: <= 10 characters

    gender string

    Possible values: [GENDER_UNSPECIFIED, GENDER_FEMALE, GENDER_MALE, GENDER_DIVERSE]

    Default value: GENDER_UNSPECIFIED

    email object required
    email string required

    Object that contains the email address and a verified flag.

    isEmailVerified boolean

    If email verified is set to true, the email will be added as verified and the user doesn't have to verify.

    phone object

    Object that contains the number and a verified flag

    phone string

    Possible values: non-empty and <= 50 characters

    mobile phone number of the user. (use global pattern of spec https://tools.ietf.org/html/rfc3966)

    isPhoneVerified boolean
    password string
    hashedPassword object

    Use this to import hashed passwords from another system.

    value string

    Encoded hash of a password in Modular Crypt Format: https://zitadel.com/docs/concepts/architecture/secrets#hashed-secrets

    passwordChangeRequired boolean

    If this is set to true, the user has to change the password on the next login.

    requestPasswordlessRegistration boolean

    If this is set to true, you will get a link for the passwordless/passkey registration in the response.

    otpCode string
    idps object[]

    To link your user directly with an external identity provider (Identity brokering)

  • Array [
    • configId string

    Possible values: non-empty and <= 200 characters

    The internal ID of the identity provider configured in ZITADEL.

    externalUserId string

    Possible values: non-empty and <= 200 characters

    The id of the user in the external identity provider

    displayName string

    Possible values: <= 200 characters

    A display name ZITADEL can show on the linked provider.

  • ]
Responses

A successful response.

Schema
    userId string
    details object
    sequence uint64

    on read: the sequence of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    creationDate date-time

    on read: the timestamp of the first event of the object

    on create: the timestamp of the event(s) added by the manipulation

    changeDate date-time

    on read: the timestamp of the last event reduced by the projection

    on manipulation: the

    resourceOwner resource_owner is the organization an object belongs to
    passwordlessRegistration object
    link string
    lifetime deprecated: use expiration instead
    expiration string
POST /users/human/_import

Authorization

name: OAuth2type: oauth2scopes: openid,urn:zitadel:iam:org:project:id:zitadel:audflows: {
  "authorizationCode": {
    "authorizationUrl": "$CUSTOM-DOMAIN/oauth/v2/authorize",
    "tokenUrl": "$CUSTOM-DOMAIN/oauth/v2/token",
    "scopes": {
      "openid": "openid",
      "urn:zitadel:iam:org:project:id:zitadel:aud": "urn:zitadel:iam:org:project:id:zitadel:aud"
    }
  }
}

Request

Base URL
https://$CUSTOM-DOMAIN/management/v1
Bearer Token
x-zitadel-orgid — header
Content-Type
Body required
{

  "userName": "minnie-mouse",

  "profile": {

    "firstName": "Minnie",

    "lastName": "Mouse",

    "nickName": "Mini",

    "displayName": "Minnie Mouse",

    "preferredLanguage": "en",

    "gender": "GENDER_FEMALE"

  },

  "email": {

    "email": "minnie@mouse.com",

    "isEmailVerified": true

  },

  "phone": {

    "phone": "+41 71 000 00 00",

    "isPhoneVerified": true

  },

  "password": "string",

  "hashedPassword": {

    "value": "$2y$12$hXUrnqdq1RIIYZ2HPytIIe5lXdIvbhqrTvdPsSF7o.jFh817Z6lwm"

  },

  "passwordChangeRequired": true,

  "requestPasswordlessRegistration": true,

  "otpCode": "string",

  "idps": [

    {

      "configId": "idp-config-id",

      "externalUserId": "idp-config-id",

      "displayName": "minnie.mouse@gmail.com"

    }

  ]

}
Accept
curl / cURL
curl -L -X POST 'https://$CUSTOM-DOMAIN/management/v1/users/human/_import' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "userName": "minnie-mouse",
  "profile": {
    "firstName": "Minnie",
    "lastName": "Mouse",
    "nickName": "Mini",
    "displayName": "Minnie Mouse",
    "preferredLanguage": "en",
    "gender": "GENDER_FEMALE"
  },
  "email": {
    "email": "minnie@mouse.com",
    "isEmailVerified": true
  },
  "phone": {
    "phone": "+41 71 000 00 00",
    "isPhoneVerified": true
  },
  "password": "string",
  "hashedPassword": {
    "value": "$2y$12$hXUrnqdq1RIIYZ2HPytIIe5lXdIvbhqrTvdPsSF7o.jFh817Z6lwm"
  },
  "passwordChangeRequired": true,
  "requestPasswordlessRegistration": true,
  "otpCode": "string",
  "idps": [
    {
      "configId": "idp-config-id",
      "externalUserId": "idp-config-id",
      "displayName": "minnie.mouse@gmail.com"
    }
  ]
}'