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/organizations

​
Description

Create a new organization with an administrative user. If no specific roles are sent for the users, they will be granted the role ORG_OWNER.

​
Required Permission

  • org.create

​
Request Body

​
name
string
required
Name is the unique name of the organization to be created. This must be unique across the instance.Min Length: 1
Max Length: 200
​
admins
array
Specify users to be assigned as organization admins. If no users are specified, the organization will be created without any admin users.
​
userId
string
Existing user ID to make an admin.
​
human
object
Create a new human user as admin.
​
profile
object
required
Profile information.
​
email
object
required
Email information.
​
roles
array
Org member roles for the admin (default is ORG_OWNER if empty).
​
organizationId
string
Optional unique identifier for the organization. If omitted, the system will generate one, which is the recommended way.Max Length: 200

​
Response

​
details
object
Metadata about the creation.
​
sequence
string
Sequence number.
​
changeDate
timestamp
Creation timestamp.
​
organizationId
string
The unique identifier of the newly created organization.
​
createdAdmins
array
Information about created admin users.
​
userId
string
User ID of the created admin.
​
emailCode
string
Email verification code if applicable.
​
phoneCode
string
Phone verification code if applicable.

​
Example Request

curl -X POST https://your-domain.zitadel.cloud/v2/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corporation",
    "admins": [
      {
        "human": {
          "profile": {
            "givenName": "John",
            "familyName": "Doe"
          },
          "email": {
            "email": "john.doe@acme.com"
          }
        },
        "roles": ["ORG_OWNER"]
      }
    ]
  }'

​
Example Response

{
  "details": {
    "sequence": "1",
    "changeDate": "2024-03-15T10:00:00Z"
  },
  "organizationId": "69629026806489455",
  "createdAdmins": [
    {
      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a"
    }
  ]
}

​
Error Responses

  • 400 Bad Request - Invalid organization data
  • 403 Forbidden - Insufficient permissions
  • 409 Conflict - Organization name already exists