Skip to main content

Setup Organization​

Create a new organization with an administrative user. If no specific roles are sent for the first user, the user will get the role ORG_OWNER.

Request Body required

Request to set up an organization. User is required

    org object required
    name string required

    Possible values: non-empty and <= 200 characters

    domain string

    Possible values: <= 200 characters

    ZITADEL generates a domain (.zitadel.ch) for an organization, the field is not required

    human object
    userName string required

    Possible values: non-empty and <= 200 characters

    profile object required
    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

    a user can set the display name if nothing is set ZITADEL computes "first_name last_name"

    preferredLanguage string

    Possible values: <= 10 characters

    language tag analog https://tools.ietf.org/html/rfc3066

    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

    email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)

    isEmailVerified boolean
    phone object
    phone has to be a global number required

    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 required

    the initial password of the user

    roles string[]
Responses

org, user and user membership were created successfully

Schema
    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
    orgId string
    userId string
POST /orgs/_setup

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

  "org": {

    "name": "ZITADEL",

    "domain": "zitadel.cloud"

  },

  "human": {

    "userName": "gigi-giraffe",

    "profile": {

      "firstName": "Gigi",

      "lastName": "Giraffe",

      "nickName": "gigi-giraffe",

      "displayName": "Gigi Giraffe",

      "preferredLanguage": "en",

      "gender": "GENDER_UNSPECIFIED"

    },

    "email": {

      "email": "gigi@zitadel.com",

      "isEmailVerified": true

    },

    "phone": {

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

      "isPhoneVerified": true

    },

    "password": "my_53cr3t-P4$$w0rd"

  },

  "roles": [

    "string"

  ]

}
Accept
curl / cURL
curl -L -X POST 'https://$CUSTOM-DOMAIN/admin/v1/orgs/_setup' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "org": {
    "name": "ZITADEL",
    "domain": "zitadel.cloud"
  },
  "human": {
    "userName": "gigi-giraffe",
    "profile": {
      "firstName": "Gigi",
      "lastName": "Giraffe",
      "nickName": "gigi-giraffe",
      "displayName": "Gigi Giraffe",
      "preferredLanguage": "en",
      "gender": "GENDER_UNSPECIFIED"
    },
    "email": {
      "email": "gigi@zitadel.com",
      "isEmailVerified": true
    },
    "phone": {
      "phone": "+41 71 000 00 00",
      "isPhoneVerified": true
    },
    "password": "my_53cr3t-P4$$w0rd"
  },
  "roles": [
    "string"
  ]
}'