> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-chore-teams-api-autoupdate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a tenant under the current team

> This endpoint creates a new tenant under your team. Upon successful creation, the response includes the tenant's details and management client credentials. The tenant type (public or private) is determined by the attributes in the request payload. Refer to the payload schema for required attributes.

export const Scopes = ({scopes = []}) => {
  return <div>
      <div class="api-section-heading flex flex-col gap-y-4 w-full">
        <div class="flex items-baseline border-b pb-2.5 border-gray-100 dark:border-gray-800 w-full">
          <h4 class="api-section-heading-title flex-1 mb-0">Scopes</h4>
          <div class="flex items-center"></div>
        </div>
      </div>
      <div class="mt-4">
        <div class="space-y-4 whitespace-normal prose prose-sm prose-gray dark:prose-invert overflow-wrap-anywhere [&_*]:overflow-wrap-anywhere">
          <p class="whitespace-pre-line text-xs">
            {"Scopes define permissions and access levels for API requests and authentication tokens."}
          </p>
        </div>
      </div>
      <div class="flex font-mono text-sm group/param-head param-head break-all relative mt-6" id="scopes-scopes">
        <div class="flex-1 flex flex-col content-start py-0.5 mr-5">
          <div class="flex items-center flex-wrap gap-2">
            <div class="absolute -top-1.5">
              <a href="#scopes-scopes" class="-ml-10 flex items-center opacity-0 border-0 group-hover/param-head:opacity-100 focus:opacity-100 focus:outline-0 py-2 [.expandable-content_&]:-ml-[2.1rem] group/link" aria-label="Navigate to header">
                ​
                <div class="w-6 h-6 rounded-md flex items-center justify-center shadow-sm text-gray-400 dark:text-white/50 dark:bg-background-dark dark:brightness-[1.35] dark:ring-1 dark:hover:brightness-150 bg-white ring-1 ring-gray-400/30 dark:ring-gray-700/25 hover:ring-gray-400/60 dark:hover:ring-white/20 group-focus/link:border-2 group-focus/link:border-primary dark:group-focus/link:border-primary-light">
                  <svg xmlns="http://www.w3.org/2000/svg" fill="gray" height="12px" viewBox="0 0 576 512">
                    <path d="M0 256C0 167.6 71.6 96 160 96h72c13.3 0 24 10.7 24 24s-10.7 24-24 24H160C98.1 144 48 194.1 48 256s50.1 112 112 112h72c13.3 0 24 10.7 24 24s-10.7 24-24 24H160C71.6 416 0 344.4 0 256zm576 0c0 88.4-71.6 160-160 160H344c-13.3 0-24-10.7-24-24s10.7-24 24-24h72c61.9 0 112-50.1 112-112s-50.1-112-112-112H344c-13.3 0-24-10.7-24-24s10.7-24 24-24h72c88.4 0 160 71.6 160 160zM184 232H392c13.3 0 24 10.7 24 24s-10.7 24-24 24H184c-13.3 0-24-10.7-24-24s10.7-24 24-24z"></path>
                  </svg>
                </div>
              </a>
            </div>
            {scopes.map((scope, index) => {
    return <span class="flex items-center px-2 py-0.5 rounded-md bg-gray-100/50 dark:bg-white/5 text-gray-600 dark:text-gray-200 font-medium break-all" style={{
      lineHeight: "1rem",
      fontSize: "0.75rem",
      fontFamily: 'var(--font-jetbrains-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace'
    }} data-component-part="field-info-pill" key={index}>
                  {scope}
                </span>;
  })}
          </div>
        </div>
      </div>
    </div>;
};

export const ApiReleaseLifecycle = ({releaseLifecycle = 'GA'}) => {
  const lifecycleMap = {
    ea: 'Early Access',
    ga: 'Generally Available',
    deprecated: 'Deprecated',
    planned: 'Planned',
    beta: 'Beta'
  };
  const LIFECYCLE_THEMES = {
    info: {
      light: {
        bg: 'lab(91.896% .077188 -6.94053)',
        text: 'lab(36.091% 25.9241 -68.0384)'
      },
      dark: {
        bg: 'lab(16.0426% 6.71726 -27.2409)',
        text: 'lab(72.6029% 4.08953 -41.9669)'
      }
    },
    secondary: {
      light: {
        bg: 'lab(90.8548% 11.3355 8.01476)',
        text: 'lab(47.5286% 56.4238 43.4706)'
      },
      dark: {
        bg: 'lab(16.3609% 37.191 25.6346)',
        text: 'lab(71.881% 41.5 29.4839)'
      }
    },
    danger: {
      light: {
        bg: 'lab(94.7916% -.0000298023 0)',
        text: 'lab(54.3656% 0 -.0000119209)'
      },
      dark: {
        bg: 'lab(13.232% 0 0)',
        text: 'lab(51.6164% 0 0)'
      }
    }
  };
  const LIFECYCLE_THEME_MAP = {
    ea: 'info',
    ga: 'info',
    beta: 'info',
    deprecated: 'secondary',
    planned: 'danger'
  };
  const lifecycle = releaseLifecycle.toLocaleLowerCase();
  const lifecycleText = lifecycleMap[lifecycle];
  if (!lifecycleText) {
    return null;
  }
  const theme = LIFECYCLE_THEMES[LIFECYCLE_THEME_MAP[lifecycle]];
  return <div>
      <div className="api-section-heading flex flex-col gap-y-4 w-full">
        <div className="flex items-baseline border-b pb-2.5 border-gray-100 dark:border-gray-800 w-full">
          <h4 className="api-section-heading-title flex-1 mb-0">
            Release Lifecycle
          </h4>
        </div>
      </div>
      <div className="flex font-mono text-sm group/param-head param-head break-all relative mt-2.5" id="releaselifecycle-lifecycle">
        <div className="flex-1 flex flex-col content-start py-0.5 mr-5">
          <div className="flex items-center flex-wrap gap-2">
            <div className="absolute -top-1.5">
              <a href="#releaselifecycle-lifecycle" className="-ml-10 flex items-center opacity-0 border-0 group-hover/param-head:opacity-100 focus:opacity-100 focus:outline-0 py-2 [.expandable-content_&]:-ml-[2.1rem] group/link" aria-label="Navigate to header">
                <div className="w-6 h-6 rounded-md flex items-center justify-center shadow-sm text-gray-400 dark:text-white/50 dark:bg-background-dark dark:brightness-[1.35] dark:ring-1 dark:hover:brightness-150 bg-white ring-1 ring-gray-400/30 dark:ring-gray-700/25 hover:ring-gray-400/60 dark:hover:ring-white/20 group-focus/link:border-2 group-focus/link:border-primary dark:group-focus/link:border-primary-light">
                  <svg xmlns="http://www.w3.org/2000/svg" fill="gray" height="12px" viewBox="0 0 576 512">
                    <path d="M0 256C0 167.6 71.6 96 160 96h72c13.3 0 24 10.7 24 24s-10.7 24-24 24H160C98.1 144 48 194.1 48 256s50.1 112 112 112h72c13.3 0 24 10.7 24 24s-10.7 24-24 24H160C71.6 416 0 344.4 0 256zm576 0c0 88.4-71.6 160-160 160H344c-13.3 0-24-10.7-24-24s10.7-24 24-24h72c61.9 0 112-50.1 112-112s-50.1-112-112-112H344c-13.3 0-24-10.7-24-24s10.7-24 24-24h72c88.4 0 160 71.6 160 160zM184 232H392c13.3 0 24 10.7 24 24s-10.7 24-24 24H184c-13.3 0-24-10.7-24-24s10.7-24 24-24z"></path>
                  </svg>
                </div>
              </a>
            </div>
            <span className="inline-flex items-center w-fit font-medium gap-1 py-0.5 px-2 rounded-md" style={{
    lineHeight: '1rem',
    fontSize: '0.75rem',
    fontFamily: 'var(--font-jetbrains-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
    backgroundColor: `light-dark(${theme.light.bg}, ${theme.dark.bg})`,
    color: `light-dark(${theme.light.text}, ${theme.dark.text})`,
    borderColor: `light-dark(color-mix(in oklab, ${theme.light.text} 25%, transparent), color-mix(in oklab, ${theme.dark.text} 25%, transparent))`
  }}>
              {lifecycleText}
            </span>
          </div>
        </div>
      </div>
    </div>;
};

<ApiReleaseLifecycle releaseLifecycle="beta" />

<Scopes scopes={["create:tenants"]} />


## OpenAPI

````yaml teams-api-oas post /api/tenants
openapi: 3.1.0
info:
  contact: {}
  title: Teams API
  version: 1.0.0
  description: >-
    The Teams API provides programmatic access to manage team members, tenants,
    environments, and activity logs for your Auth0 team.
servers:
  - url: https://{teamSlug}.teams.auth0.com
    description: The base URL for Teams API
    variables:
      teamSlug:
        default: teamSlug
        description: Team slug
security:
  - Bearer: []
tags:
  - name: Members
    description: Operations related to team members
  - name: Tenants
    description: Operations related to tenants
  - name: Environments
    description: Operations related to environments
  - name: Activity
    description: Operations related to team activity logs
paths:
  /api/tenants:
    post:
      tags:
        - Tenants
      summary: Create a tenant under the current team
      description: >-
        This endpoint creates a new tenant under your team. Upon successful
        creation, the response includes the tenant's details and management
        client credentials. The tenant type (public or private) is determined by
        the attributes in the request payload. Refer to the payload schema for
        required attributes.
      operationId: createTenant
      requestBody:
        $ref: '#/components/requestBodies/CreateTenantsRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateTenantsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
      security:
        - Bearer:
            - create:tenants
      x-codeSamples: []
components:
  requestBodies:
    CreateTenantsRequest:
      description: Create a tenant under the current team
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTenantsRequestContent'
  responses:
    CreateTenantsResponse:
      description: Tenant Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTenantsResponseContent'
    BadRequestResponse:
      description: Invalid input based on schema.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 400
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 400
                type: VALIDATION_ERROR
                title: Invalid payload
    UnauthorizedResponse:
      description: Token has expired or signature is invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 401
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 401
                type: UNAUTHORIZED
                title: Unauthorized
    ForbiddenResponse:
      description: Forbidden. The message will vary depending on the cause.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 403
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 403
                type: TENANT_LIMIT_REACHED
                title: You have reached the limit for tenants in your current plan
    NotFoundResponse:
      description: Not Found. The message will vary depending on the cause.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 404
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 404
                type: TENANT_NOT_FOUND
                title: The tenant was not found
    ConflictResponse:
      description: Conflict. The message will vary depending on the cause.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 409
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 409
                type: TENANT_ALREADY_EXISTS
                title: A tenant with the same name already exists
    TooManyRequestsResponse:
      description: Too Many Requests. The message will vary depending on the cause.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 429
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 429
                type: TOO_MANY_REQUESTS
                title: Too many requests
    InternalServerErrorResponse:
      description: >-
        Internal Server Error. The server encountered an unexpected condition
        and could not fulfill the request.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                const: 500
              type:
                type: string
              title:
                type: string
              details:
                type: string
            required:
              - status
              - type
              - title
            examples:
              - status: 500
                type: UNKNOWN_ERROR
                title: An unknown error occurred
  schemas:
    CreateTenantsRequestContent:
      oneOf:
        - $ref: '#/components/schemas/PublicCloudPayload'
        - $ref: '#/components/schemas/PrivateCloudPayload'
    CreateTenantsResponseContent:
      oneOf:
        - $ref: '#/components/schemas/PublicCloudResponseContent'
        - $ref: '#/components/schemas/PrivateCloudResponseContent'
    PublicCloudPayload:
      title: Public Cloud
      type: object
      properties:
        tenant_name:
          $ref: '#/components/schemas/TenantName'
        admin_email:
          $ref: '#/components/schemas/AdminEmail'
        locality:
          $ref: '#/components/schemas/PublicCloudRegion'
        environment_tag:
          $ref: '#/components/schemas/EnvironmentTypeEnum'
          default: development
      required:
        - admin_email
        - locality
      additionalProperties: false
    PrivateCloudPayload:
      title: Private Cloud
      type: object
      properties:
        tenant_name:
          $ref: '#/components/schemas/TenantName'
        admin_email:
          $ref: '#/components/schemas/AdminEmail'
        environment:
          $ref: '#/components/schemas/PrivateCloudEnvironment'
      required:
        - admin_email
        - environment
      additionalProperties: false
    PublicCloudResponseContent:
      title: Public Cloud
      type: object
      properties:
        tenant_id:
          type: string
          format: uuid
          examples:
            - 538c9e21-e3d5-4ad6-b3d0-352c62369fb0
          description: >-
            The unique identifier of the created tenant (UUID). This identifier
            is required for performing operations such as deleting the tenant.
            UUIDs ensure global uniqueness and are essential for managing tenant
            resources programmatically
        tenant_name:
          $ref: '#/components/schemas/TenantName'
        domain:
          $ref: '#/components/schemas/TenantFqdn'
        environment_tag:
          $ref: '#/components/schemas/EnvironmentTypeEnum'
        locality:
          $ref: '#/components/schemas/Region'
        environment:
          $ref: '#/components/schemas/Environment'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        management_client:
          $ref: '#/components/schemas/ManagementClient'
      required:
        - tenant_id
        - tenant_name
        - domain
        - locality
        - environment
        - created_at
        - management_client
    PrivateCloudResponseContent:
      title: Private Cloud
      type: object
      properties:
        tenant_id:
          type: string
          format: uuid
          examples:
            - 538c9e21-e3d5-4ad6-b3d0-352c62369fb0
          description: >-
            The unique identifier of the created tenant (UUID). This identifier
            is required for performing operations such as deleting the tenant.
            UUIDs ensure global uniqueness and are essential for managing tenant
            resources programmatically
        tenant_name:
          $ref: '#/components/schemas/TenantName'
        domain:
          $ref: '#/components/schemas/TenantFqdn'
        environment:
          $ref: '#/components/schemas/Environment'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        management_client:
          $ref: '#/components/schemas/ManagementClient'
      required:
        - tenant_id
        - tenant_name
        - domain
        - environment
        - created_at
        - management_client
      additionalProperties: false
    TenantName:
      type: string
      pattern: ^[a-z0-9][-a-z0-9]{1,62}[a-z0-9]$
      minLength: 3
      maxLength: 63
      examples:
        - acme-development-tenant
      description: >-
        The tenant name uniquely identifies a tenant programmatically and within
        various dashboards, such as Auth0 Dashboard. It can only contain
        alphanumeric characters, lowercase letters and "-". However, it can't
        start nor end with "-". If not specified, a tenant name will be
        auto-generated.
    AdminEmail:
      type: string
      format: email
      description: >-
        The email of the person that will be added as an admin of the tenant.
        The person must be a member of the team.
    PublicCloudRegion:
      type: string
      description: >-
        Specifies the Auth0 Public Cloud locality where the tenant will be
        created.<br> Available localities include United States (us), Europe
        (eu), Australia (au), Japan (jp), Canada (ca) and United Kingdom (uk).
      minLength: 2
      maxLength: 5
      examples:
        - us
        - eu
        - au
        - jp
        - ca
        - uk
    EnvironmentTypeEnum:
      type: string
      description: >-
        Specifies the Environment tag for the tenant created in the Auth0 Public
        Cloud. It is used to distinguish between development, staging and
        production environments.<br> Development and Staging environments are
        intended for testing and pre-production use, while production is
        designated for live applications and subject to higher rate limits.
        Selecting the correct environment type ensures appropriate resource
        allocation and rate limits
      enum:
        - development
        - production
        - staging
      examples:
        - development
    PrivateCloudEnvironment:
      type: string
      minLength: 1
      maxLength: 32
      pattern: ^[a-z]([-]?[a-z0-9])*$
      examples:
        - acme-dev
      description: >-
        Specifies the name of the Auth0 Private Cloud environment where the
        tenant will be created.
    TenantFqdn:
      type: string
      description: >-
        The fully qualified domain name of the tenant, which uniquely identifies
        its domain within the system. The domain is used to define the audience
        when interacting with the Management API, enabling programmatic
        management of the tenant’s configuration and resources.
      examples:
        - acme-development-tenant.us.auth0.com
        - acme-development-tenant.acme-dev.auth0app.com
    Region:
      type: string
      description: Locality in which the tenant was created
      examples:
        - us
        - eu
        - virginia
        - frankfurt
    Environment:
      type: string
      description: The name of the cloud environment where the tenant was created
      examples:
        - US-3
        - EU-1
        - acme-dev
    CreatedAt:
      type: string
      description: >-
        The date and time when the tenant was created, formatted in ISO 8601
        standard. This timestamp ensures consistency across time zones and
        systems
      format: date-time
    ManagementClient:
      type: object
      description: >-
        The Auth0 Management Client credentials required to authenticate and
        interact with the newly created tenant. These credentials allow
        authorized access to manage the tenant's configuration, resources, and
        API interactions.
      properties:
        client_name:
          type: string
          description: >-
            The name of the Machine to Machine client, which is used for secure,
            automated interactions with the tenant's APIs and services.
        client_id:
          type: string
          description: >-
            The id of the Machine to Machine client, which is used for secure,
            automated interactions with the tenant's APIs and services.
        client_secret:
          type: string
          description: >-
            The client secret the Machine to Machine client, which is used for
            secure, automated interactions with the tenant's APIs and services.
      required:
        - client_name
        - client_id
        - client_secret
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````