Skip to main content

Create a user​

Create a new user with an optional data schema.

Request Body required
    userId string

    Possible values: non-empty and <= 200 characters

    Optionally set a unique identifier of the user. If unset, ZITADEL will take care of it.

    organization object required

    Set the organization the user belongs to.

    orgId string
    orgDomain string
    authenticators object

    Set the initial authenticators of the user.

    usernames object[]
  • Array [
    • username string required

    Possible values: non-empty and <= 200 characters

    Set the user's username. This will be used for identification during authentication.

    isOrganizationSpecific boolean

    By default username must be unique across all organizations in an instance. This option allow to restrict the uniqueness to the user's own organization. As a result, this username can only be used if the authentication is limited to the corresponding organization.

    This can be useful if you provide multiple usernames for a single user, where one if specific to your organization, e.g.:

    • gigi-giraffe@zitadel.com (unique across organizations)
    • gigi-giraffe (unique only inside the ZITADEL organization)
  • ]
    • password object
    password string required

    Possible values: non-empty and <= 200 characters

    Provide the plain text password. ZITADEL will take care to store it in a secure way (hash).

    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

    Provide if the user needs to change the password on the next use.

    contact object

    Set the contact information (email, phone) for the user.

    email object
    address string required

    Possible values: non-empty and <= 200 characters

    Set the email address.

    sendCode object

    Let ZITADEL send the link to the user via email.

    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

    Get the code back to provide it to the user in your preferred mechanism.

    isVerified boolean

    Set the email as already verified.

    phone object
    number string required

    Possible values: non-empty and <= 20 characters

    Set the user's phone number.

    sendCode object

    Let ZITADEL send the link to the user via SMS.

    returnCode object

    Get the code back to provide it to the user in your preferred mechanism.

    isVerified boolean

    Set the phone as already verified.

    schemaId string required

    Possible values: non-empty and <= 200 characters

    Define the schema the user's data schema by providing it's ID.

    data object

    Provide data about the user. It will be validated based on the specified schema.

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

    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

    The email code will be set if a contact email was set with a return_code verification option.

    phoneCode string

    The phone code will be set if a contact phone was set with a return_code verification option.

POST /v3alpha/users

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": "69629026806489455",

  "organization": {

    "orgId": "string",

    "orgDomain": "string"

  },

  "authenticators": {

    "usernames": [

      {

        "username": "gigi-giraffe",

        "isOrganizationSpecific": true

      }

    ],

    "password": {

      "password": "Secr3tP4ssw0rd!",

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

      "changeRequired": true

    }

  },

  "contact": {

    "email": {

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

      "sendCode": {

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

      },

      "returnCode": {},

      "isVerified": true

    },

    "phone": {

      "number": "+41791234567",

      "sendCode": {},

      "returnCode": {},

      "isVerified": true

    }

  },

  "schemaId": "69629026806489455",

  "data": {

    "name": "Gigi",

    "description": "the giraffe"

  }

}
Accept
curl / cURL
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "userId": "69629026806489455",
  "organization": {
    "orgId": "string",
    "orgDomain": "string"
  },
  "authenticators": {
    "usernames": [
      {
        "username": "gigi-giraffe",
        "isOrganizationSpecific": true
      }
    ],
    "password": {
      "password": "Secr3tP4ssw0rd!",
      "hash": "$2a$12$lJ08fqVr8bFJilRVnDT9QeULI7YW.nT3iwUv6dyg0aCrfm3UY8XR2",
      "changeRequired": true
    }
  },
  "contact": {
    "email": {
      "address": "mini@mouse.com",
      "sendCode": {
        "urlTemplate": "https://example.com/email/verify?userID={{.UserID}}&code={{.Code}}&orgID={{.OrgID}}"
      },
      "returnCode": {},
      "isVerified": true
    },
    "phone": {
      "number": "+41791234567",
      "sendCode": {},
      "returnCode": {},
      "isVerified": true
    }
  },
  "schemaId": "69629026806489455",
  "data": {
    "name": "Gigi",
    "description": "the giraffe"
  }
}'