Microsoft Azure CIAMTenants API

openapi: 3.2.0
info:
  title: Microsoft Azure ExternalIdentities CIAM Tenants API
  version: 2023-05-17-preview
  description: Manage the Azure resource for an Azure Active Directory B2C tenant, Guest Usages, and Azure AD for customers resource for External Identities in Azure AD
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: CIAMTenants
paths:
  /subscriptions/{subscriptionId}/providers/Microsoft.AzureActiveDirectory/checkNameAvailability:
    post:
      tags:
      - CIAMTenants
      operationId: microsoftAzureChecknameavailability
      description: Checks the availability and validity of a domain name for the tenant.
      x-ms-examples:
        Check name availability - available:
          $ref: ./examples/checkNameAvailability-available.json
        Check name availability - taken:
          $ref: ./examples/checkNameAvailability-taken.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: The result of checking for the name availability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameAvailabilityResponse'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      summary: Post Subscriptions Subscriptionid Providers Microsoft Azureactivedirectory…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckNameAvailabilityRequestBody'
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureActiveDirectory/ciamDirectories
  : get:
      description: Get all the Azure AD for customers tenants resources in a resource group.
      operationId: microsoftAzureCiamtenantsListbyresourcegroup
      tags:
      - CIAMTenants
      x-ms-examples:
        CIAMTenants_ListByResourceGroup:
          $ref: ./examples/CIAM/listCIAMTenantsByResourceGroup.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      responses:
        '200':
          description: List of Azure AD for customers tenants in resource group successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CIAMTenantResourceList'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Get Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers…
  /subscriptions/{subscriptionId}/providers/Microsoft.AzureActiveDirectory/ciamDirectories:
    get:
      description: Get all the Azure AD for customers tenant resources in a subscription.
      operationId: microsoftAzureCiamtenantsListbysubscription
      tags:
      - CIAMTenants
      x-ms-examples:
        CIAMTenants_ListBySubscription:
          $ref: ./examples/CIAM/listCIAMTenantsBySubscription.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: Azure AD for customers tenant resources in subscription successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CIAMTenantResourceList'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-pageable:
        nextLinkName: null
      summary: Get Subscriptions Subscriptionid Providers Microsoft Azureactivedirectory…
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureActiveDirectory/ciamDirectories/{resourceName}
  : get:
      description: Get the Azure AD for customers tenant resource.
      operationId: microsoftAzureCiamtenantsGet
      tags:
      - CIAMTenants
      x-ms-examples:
        Get_CIAM_tenant:
          $ref: ./examples/CIAM/getCIAMTenant.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/components/parameters/CIAMResourceNameParameter'
      responses:
        '200':
          description: Azure AD for customers tenant resource successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CIAMTenantResource'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      summary: Get Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers…
    put:
      operationId: microsoftAzureCiamtenantsCreate
      description: 'Initiates an async request to create both the Azure AD for customers tenant and the corresponding Azure resource linked to a subscription. Note: Please check name availability before creating a new tenant'
      x-ms-examples:
        Create_CIAM_tenant:
          $ref: ./examples/CIAM/createCIAMTenant.json
      tags:
      - CIAMTenants
      parameters:
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/components/parameters/CIAMResourceNameParameter'
      responses:
        '200':
          description: OK - Successfully updated an existing Azure AD for customers tenant resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CIAMTenantResource'
        '201':
          description: Azure AD for customers tenant create request was successfully started and will complete asynchronously.
          headers:
            Azure-AsyncOperation:
              description: The URL to retrieve the status of the asynchronous operation.
              schema:
                type: string
            Retry-After:
              description: Contains the number of seconds to wait before polling the location.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CIAMTenantResource'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: azure-async-operation
      summary: Put Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CIAMTenantResource'
        description: Request body to create an Azure AD for customers tenant
        required: true
    patch:
      description: Update the Azure AD for customers tenant resource.
      operationId: microsoftAzureCiamtenantsUpdate
      tags:
      - CIAMTenants
      x-ms-examples:
        Update_CIAM_tenant:
          $ref: ./examples/CIAM/updateCIAMTenant.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/components/parameters/CIAMResourceNameParameter'
      responses:
        '200':
          description: Updated the Azure AD for customers tenant resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CIAMTenantResource'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      summary: Patch Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CIAMTenantUpdateRequest'
        description: Request body to update Azure AD for customers tenant resource.
    delete:
      operationId: microsoftAzureCiamtenantsDelete
      description: Initiates an async operation to delete the Azure AD for customers tenant and Azure resource. The resource deletion can only happen as the last step in the tenant deletion process.
      x-ms-examples:
        Delete_CIAM_tenant:
          $ref: ./examples/CIAM/deleteCIAMTenant.json
      tags:
      - CIAMTenants
      parameters:
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/components/parameters/CIAMResourceNameParameter'
      responses:
        '202':
          description: 'Resource deletion request accepted. The Azure-AsyncOperation header indicates the URL/location in which to poll for a result of the asynchronous operation. '
          headers:
            Azure-AsyncOperation:
              description: The URL to retrieve the status of the asynchronous operation.
              schema:
                type: string
            Location:
              description: The URL to retrieve the status of the asynchronous operation.
              schema:
                type: string
            Retry-After:
              description: Contains the number of seconds to wait before checking the deletion status.
              schema:
                type: string
        '204':
          description: NoContent - Azure AD for customers tenant resource successfully deleted or didn't exist.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: location
      summary: Delete Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers…
components:
  schemas:
    ProvisioningState:
      title: Provisioning State
      type: string
      readOnly: true
      enum:
      - Succeeded
      - Failed
      - Canceled
      - Provisioning
      - Deleting
      - Deleted
      x-ms-enum:
        name: ProvisioningState
        modelAsString: true
    CIAMTenantResourceProperties:
      description: Properties of the Azure AD for customers tenant Azure resource.
      type: object
      required:
      - createTenantProperties
      properties:
        provisioningState:
          $ref: '#/components/schemas/ProvisioningState'
        createTenantProperties:
          $ref: '#/components/schemas/CreateCIAMTenantProperties'
        domainName:
          type: string
          description: The domain name of the tenant
          readOnly: true
        billingConfig:
          type: object
          description: The billing configuration for the tenant.
          x-ms-client-flatten: true
          readOnly: true
          properties:
            billingType:
              type: string
              readOnly: true
              description: The type of billing. Will be MAU for all new customers. Cannot be changed if value is 'MAU'. Learn more about Azure AD for customers billing at [aka.ms/b2cBilling](https://aka.ms/b2cbilling).
              enum:
              - MAU
              x-ms-enum:
                name: ciamBillingType
                modelAsString: true
                values:
                - value: MAU
                  description: Azure AD for customers usage is billed to a linked Azure subscription and uses a monthly active users (MAU) billing model.
            effectiveStartDateUtc:
              type: string
              readOnly: true
              description: The data from which the billing type took effect
        tenantId:
          type: string
          description: An identifier of the Azure AD for customers tenant.
          x-ms-mutability:
          - create
          - read
    CIAMTenantResourceList:
      description: The collection of Azure AD for customers tenant resources
      type: object
      properties:
        value:
          description: List of Azure AD for customers tenant resources
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/CIAMTenantResource'
        nextLink:
          description: The URL to get the next set of Azure AD for customers tenant resources.
          type:
          - string
          - 'null'
          readOnly: true
    NameAvailabilityResponse:
      description: Response of the CheckNameAvailability operation.
      type: object
      properties:
        message:
          type: string
          description: Description of the reason if name is not available.
        nameAvailable:
          type: boolean
          description: True if the name is available and can be used to create a new tenant. Otherwise false.
        reason:
          $ref: '#/components/schemas/NameAvailabilityReason'
    CloudError:
      x-ms-external: true
      type: object
      properties:
        error:
          $ref: ../../../../../common-types/resource-management/v1/types.json#/definitions/ErrorResponse
      description: An error response for a resource management request.
    CountryCode:
      type: string
      description: Country code of Azure tenant (e.g. 'US'). Refer to [aka.ms/B2CDataResidency](https://aka.ms/B2CDataResidency) to see valid country codes and corresponding data residency locations. If you do not see a country code in an valid data residency location, choose one from the list.
    NameAvailabilityReason:
      description: Describes the reason for the 'nameAvailable' value.
      type: string
      enum:
      - AlreadyExists
      - Invalid
      x-ms-enum:
        name: NameAvailabilityReasonType
        modelAsString: true
        values:
        - value: AlreadyExists
          description: The name is already in use and is therefore unavailable.
        - value: Invalid
          description: The name provided does not match the resource provider’s naming requirements (incorrect length, unsupported characters, etc.).
    CIAMTenantUpdateRequest:
      type: object
      description: The request body to update the Azure AD for customers tenant resource.
      properties:
        sku:
          $ref: '#/components/schemas/CIAMResourceSKU'
        tags:
          type: object
          additionalProperties:
            type: string
          description: Resource Tags
    CIAMResourceSKU:
      description: SKU properties of the Azure AD for customers tenant. Learn more about Azure AD for customers billing at [https://aka.ms/ciambilling](https://aka.ms/ciambilling).
      type: object
      required:
      - name
      - tier
      properties:
        name:
          type: string
          description: The name of the SKU for the tenant.
          enum:
          - Standard
          - PremiumP1
          - PremiumP2
          x-ms-enum:
            name: CIAMResourceSKUName
            modelAsString: true
        tier:
          type: string
          description: The tier of the tenant.
          enum:
          - A0
          x-ms-mutability:
          - create
          - read
          x-ms-client-flatten: true
          x-ms-enum:
            name: CIAMResourceSKUTier
            modelAsString: true
            values:
            - value: A0
              description: The SKU tier used for all Azure AD for customers tenants.
    CIAMTenantResource:
      type: object
      description: The Azure AD for customers resource.
      required:
      - location
      - sku
      - properties
      x-ms-azure-resource: true
      properties:
        id:
          type: string
          readOnly: true
          description: An identifier that represents the Azure AD for customers tenant resource.
        name:
          type: string
          readOnly: true
          description: The name of the Azure AD for customers tenant resource.
        type:
          type: string
          description: The type of the Azure AD for customers tenant resource.
          readOnly: true
          enum:
          - Microsoft.AzureActiveDirectory/ciamDirectories
          x-ms-enum:
            name: ciamTypeValue
            modelAsString: true
            values:
            - value: Microsoft.AzureActiveDirectory/ciamDirectories
              description: The resource type for Azure AD for customers tenant resource.
        location:
          type: string
          description: The location in which the resource is hosted and data resides. Can be one of 'United States', 'Europe', 'Asia Pacific', or 'Australia'. Refer to [this documentation](https://aka.ms/ciam-data-location) for more information.
          x-ms-mutability:
          - create
          - read
          x-ms-enum:
            name: ciamLocationValue
            modelAsString: true
            values:
            - value: United States
              description: The location in which the resource is hosted and data resides.
            - value: Europe
              description: The location in which the resource is hosted and data resides.
            - value: Asia Pacific
              description: The location in which the resource is hosted and data resides.
            - value: Australia
              description: The location in which the resource is hosted and data resides.
        sku:
          $ref: '#/components/schemas/CIAMResourceSKU'
        properties:
          $ref: '#/components/schemas/CIAMTenantResourceProperties'
          x-ms-client-flatten: true
          description: The Azure AD for customers tenant resource properties
        tags:
          type: object
          additionalProperties:
            type: string
          description: Resource Tags
        systemData:
          $ref: ../../../../../common-types/resource-management/v5/types.json#/definitions/systemData
          readOnly: true
    CreateCIAMTenantProperties:
      type: object
      description: These properties are used to create the Azure AD for customers tenant. These properties are not part of the Azure resource.
      required:
      - displayName
      - countryCode
      x-ms-mutability:
      - create
      - read
      x-ms-client-flatten: true
      properties:
        displayName:
          description: The display name of the Azure AD for customers tenant.
          type: string
          x-ms-mutability:
          - create
          - read
        countryCode:
          type: string
          description: Country code of Azure tenant (e.g. 'US'). Refer to [https://aka.ms/ciam-data-location](https://aka.ms/ciam-data-location) to see valid country codes and corresponding data residency locations. If you do not see a country code in an valid data residency location, choose one from the list.
          x-ms-mutability:
          - create
          - read
    CheckNameAvailabilityRequestBody:
      type: object
      description: The information required to check the availability of the sub domain name for the tenant.
      required:
      - name
      - countryCode
      properties:
        name:
          type: string
          description: The sub domain name to check for availability.
        countryCode:
          $ref: '#/components/schemas/CountryCode'
  parameters:
    ApiVersionParameter:
      name: api-version
      in: query
      required: true
      description: Version of the API to be used with the client request.
      schema:
        type: string
    SubscriptionIdParameter:
      name: subscriptionId
      in: path
      required: true
      description: Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.
      schema:
        type: string
    CIAMResourceNameParameter:
      name: resourceName
      in: path
      required: true
      description: The initial sub domain of the tenant.
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 26
        pattern: ^[a-zA-Z0-9]{1,26}
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow