Skip to main content

Create a user (Human)​

Create/import a new user with the type human. The newly created user will get a verification email if either the email address is not marked as verified and you did not request the verification to be returned.

Request Body required
    userId string

    Possible values: non-empty and <= 200 characters

    optionally set your own id unique for the user.

    username string

    Possible values: non-empty and <= 200 characters

    optionally set a unique username, if none is provided the email will be used.

    organization object
    orgId string
    orgDomain string
    profile object required
    givenName string required

    Possible values: non-empty and <= 200 characters

    familyName 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

    Possible values: non-empty and <= 200 characters

    sendCode object
    urlTemplate string

    Possible values: non-empty and <= 200 characters

    "Optionally set a url_template, which will be used in the verification mail sent by ZITADEL to guide the user to your verification page. If no template is set, the default ZITADEL url will be used."

    returnCode object
    isVerified boolean
    phone object
    phone string

    Possible values: <= 200 characters

    sendCode object
    returnCode object
    isVerified boolean
    metadata object[]
  • Array [
    • key string required

    Possible values: non-empty and <= 200 characters

    value byte required

    Possible values: non-empty and <= 500000 characters

    The value has to be base64 encoded.

  • ]
    • password object
    password string required

    Possible values: non-empty and <= 200 characters

    changeRequired boolean
    hashedPassword object
    hash string required

    Possible values: non-empty and <= 200 characters

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

    changeRequired boolean
    idpLinks object[]
  • Array [
    • idpId string

    Possible values: non-empty and <= 200 characters

    ID of the identity provider

    userId string

    Possible values: non-empty and <= 200 characters

    ID of the user of the identity provider

    userName string

    Possible values: non-empty and <= 200 characters

    username of the user of the identity provider

  • ]
    • totpSecret string

    Possible values: non-empty and <= 200 characters

    An Implementation of RFC 6238 is used, with HMAC-SHA-1 and time-step of 30 seconds. Currently no other options are supported, and if anything different is used the validation will fail.

Responses

OK

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

    changeDate date-time

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

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

    resourceOwner resource_owner is the organization or instance_id an object belongs to
    emailCode string
    phoneCode string
POST /v2beta/users/human

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
Bearer Token
Content-Type
Body required
{

  "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",

  "username": "minnie-mouse",

  "organization": {

    "orgId": "string",

    "orgDomain": "string"

  },

  "profile": {

    "givenName": "Minnie",

    "familyName": "Mouse",

    "nickName": "Mini",

    "displayName": "Minnie Mouse",

    "preferredLanguage": "en",

    "gender": "GENDER_FEMALE"

  },

  "email": {

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

    "sendCode": {

      "urlTemplate": "https://example.com/email/verify?userID={{.UserID}}&code={{.Code}}&orgID={{.OrgID}}"

    },

    "returnCode": {},

    "isVerified": true

  },

  "phone": {

    "phone": "+41791234567",

    "sendCode": {},

    "returnCode": {},

    "isVerified": true

  },

  "metadata": [

    {

      "key": "my-key",

      "value": "VGhpcyBpcyBteSB0ZXN0IHZhbHVl"

    }

  ],

  "password": {

    "password": "Secr3tP4ssw0rd!",

    "changeRequired": true

  },

  "hashedPassword": {

    "hash": "$2a$12$lJ08fqVr8bFJilRVnDT9QeULI7YW.nT3iwUv6dyg0aCrfm3UY8XR2",

    "changeRequired": true

  },

  "idpLinks": [

    {

      "idpId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",

      "userId": "6516849804890468048461403518",

      "userName": "user@external.com"

    }

  ],

  "totpSecret": "TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK"

}
Accept
curl / cURL
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/users/human' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
  "username": "minnie-mouse",
  "organization": {
    "orgId": "string",
    "orgDomain": "string"
  },
  "profile": {
    "givenName": "Minnie",
    "familyName": "Mouse",
    "nickName": "Mini",
    "displayName": "Minnie Mouse",
    "preferredLanguage": "en",
    "gender": "GENDER_FEMALE"
  },
  "email": {
    "email": "mini@mouse.com",
    "sendCode": {
      "urlTemplate": "https://example.com/email/verify?userID={{.UserID}}&code={{.Code}}&orgID={{.OrgID}}"
    },
    "returnCode": {},
    "isVerified": true
  },
  "phone": {
    "phone": "+41791234567",
    "sendCode": {},
    "returnCode": {},
    "isVerified": true
  },
  "metadata": [
    {
      "key": "my-key",
      "value": "VGhpcyBpcyBteSB0ZXN0IHZhbHVl"
    }
  ],
  "password": {
    "password": "Secr3tP4ssw0rd!",
    "changeRequired": true
  },
  "hashedPassword": {
    "hash": "$2a$12$lJ08fqVr8bFJilRVnDT9QeULI7YW.nT3iwUv6dyg0aCrfm3UY8XR2",
    "changeRequired": true
  },
  "idpLinks": [
    {
      "idpId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "userId": "6516849804890468048461403518",
      "userName": "user@external.com"
    }
  ],
  "totpSecret": "TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK"
}'