ControlUp Tenants API

openapi: 3.2.0
info:
  title: DaaS IQ Tenants API
  description: 'Multi-cloud Virtual Desktop Infrastructure Management API (Default Version: v1.0)


    🔒 **Authentication**


    This API supports two authentication methods:


    **1. API Key (Bearer Token)** - Recommended for programmatic access

    - Create an API key at [API Key Management](https://support.controlup.com/docs/create-an-api-key)

    - Include in requests: `Authorization: Bearer YOUR_API_KEY`


    **2. Cookie Authentication** - For browser-based access

    - Login via DEX authentication service

    - The `user_dex_token` cookie will be automatically included'
  contact:
    name: ControlUp Support
    url: https://controlup.com/support
    email: support@controlup.com
  version: v1
  x-build-version: 1.0.107
servers:
- url: https://api.controlup.com/daas-iq/v1
tags:
- name: Tenants
paths:
  /cloud/tenants/{tenantId}/credentials:
    get:
      tags:
      - Tenants
      summary: Get tenant credentials
      description: 'Returns every credential in the tenant''s pool — the default one plus any additional service principals added for

        load balancing — with sensitive values masked.

        Describes how credentials are configured, not whether they currently work: health, cooldown, and usage metrics are absent.'
      operationId: GetTenantCredentials
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved the credentials.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CloudCredentialDto'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have view tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
    post:
      tags:
      - Tenants
      summary: Add a credential
      description: 'Adds a new credential to a tenant''s credential pool.

        This is useful for adding additional service principals for load balancing API calls.

        Automatically triggers credential verification in the background to update health status.'
      operationId: AddTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The credential creation request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCloudCredentialRequest'
        required: true
      responses:
        '201':
          description: Successfully created the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudCredentialDto'
        '400':
          description: Bad request. Invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have edit tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/{credentialId}:
    get:
      tags:
      - Tenants
      summary: Get a credential by ID
      description: 'Returns one credential''s configuration: auth type, masked secret fields, and whether it is enabled.

        Configuration only — it reports nothing about that credential''s live health, cooldown, or usage.'
      operationId: GetTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudCredentialDto'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have view tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
    put:
      tags:
      - Tenants
      summary: Update a credential
      description: 'Updates an existing credential with new authentication details.

        Automatically clears any stale operational state (cooldown, health metrics) after update.

        Automatically triggers credential verification in the background to update health status.'
      operationId: UpdateTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The credential update request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCloudCredentialRequest'
        required: true
      responses:
        '200':
          description: Successfully updated the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudCredentialDto'
        '400':
          description: Bad request. Invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have edit tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
    patch:
      tags:
      - Tenants
      summary: Patch a credential
      description: 'Partially updates a credential. Only provided fields will be updated.

        Automatically clears any stale operational state (cooldown, health metrics) after update.

        Automatically triggers credential verification in the background to update health status.'
      operationId: PatchTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The credential patch request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCloudCredentialRequest'
        required: true
      responses:
        '200':
          description: Successfully patched the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudCredentialDto'
        '400':
          description: Bad request. Invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have edit tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
    delete:
      tags:
      - Tenants
      summary: Delete a credential
      description: 'Soft deletes a credential from a tenant.

        If deleting the default credential, another credential will be automatically promoted to default (prioritizes enabled credentials, then oldest by creation date).

        Validation rules:

        - Cannot delete the only credential for a tenant

        - Cannot delete if it would leave no enabled credentials'
      operationId: DeleteTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Successfully deleted the credential.
        '400':
          description: Bad request. Validation rule violated, for example deleting the only credential or the last enabled credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have delete tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/{credentialId}/enable:
    post:
      tags:
      - Tenants
      summary: Enable a credential
      description: 'Enables a credential for use in the credential pool.

        Enabled credentials will be selected for API operations via round-robin (LRU) selection.

        Automatically clears any stale operational state (cooldown, health metrics) to provide a fresh start.'
      operationId: EnableTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully enabled the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudCredentialDto'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have edit tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/{credentialId}/disable:
    post:
      tags:
      - Tenants
      summary: Disable a credential
      description: 'Disables a credential from being used in the credential pool.

        Disabled credentials will not be selected for API operations but remain in the system.

        Cannot disable the last enabled credential for a tenant.'
      operationId: DisableTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully disabled the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudCredentialDto'
        '400':
          description: Bad request. Cannot disable the last enabled credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have edit tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/status:
    get:
      tags:
      - Tenants
      summary: Get credentials status
      description: 'Returns live operational status for every credential in the tenant: health, rate-limit cooldown, and usage metrics.

        Reports whether credentials are currently working rather than how they are configured, and covers the whole pool in one call.'
      operationId: GetTenantCredentialsPoolStatus
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved the detailed credential statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CredentialStatusDto'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have view tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/{credentialId}/status:
    get:
      tags:
      - Tenants
      summary: Get credential status
      description: 'Returns live operational status for one credential: health, rate-limit cooldown, and usage metrics.

        Reports whether that credential is currently working rather than how it is configured, and covers a single credential rather than the pool.'
      operationId: GetTenantCredentialStatus
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved the detailed credential status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialStatusDto'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have view tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/verify:
    post:
      tags:
      - Tenants
      summary: Verify default credentials
      description: 'Tests one credential live against Azure AD — the tenant''s default specifically, not round-robin selection —

        and returns step-by-step results. Success clears stale operational state such as cooldown and health metrics.

        Scoped to authentication by that single credential; refreshing the tenant status is the broader check that

        walks every subscription and updates overall tenant health.'
      operationId: VerifyTenantDefaultCredentials
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Verification completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
              example:
                isSuccess: true
                steps:
                - stepName: Authenticating with Azure AD
                  status: success
                  isSuccess: true
                  durationMs: 450
                - stepName: Listing subscriptions
                  status: success
                  isSuccess: true
                  durationMs: 320
                - stepName: Checking subscription access
                  status: success
                  isSuccess: true
                  durationMs: 180
                - stepName: Verifying Reader role
                  status: warning
                  detail: Role verification not fully implemented
                  isSuccess: false
                  durationMs: 220
                completedAt: '2025-10-09T14:30:00Z'
                durationMs: 1170
        '400':
          description: Bad request. Invalid tenant ID or tenant has no default credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have view tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/tenants/{tenantId}/credentials/{credentialId}/verify:
    post:
      tags:
      - Tenants
      summary: Verify a credential by ID
      description: 'Verifies a specific credential for a tenant. Tests authentication with Azure AD and tenant access.

        This verifies the exact credential specified - NOT round-robin selection.

        On successful verification, automatically clears any stale operational state (cooldown, health metrics).'
      operationId: VerifyTenantCredential
      parameters:
      - name: tenantId
        in: path
        description: The tenant identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: credentialId
        in: path
        description: The credential identifier to verify.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Verification completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
              example:
                isSuccess: true
                steps:
                - stepName: Authenticating with Azure AD
                  status: success
                  isSuccess: true
                  durationMs: 450
                - stepName: Listing subscriptions
                  status: success
                  isSuccess: true
                  durationMs: 320
                - stepName: Checking subscription access
                  status: success
                  isSuccess: true
                  durationMs: 180
                - stepName: Verifying Reader role
                  status: warning
                  detail: Role verification not fully implemented
                  isSuccess: false
                  durationMs: 220
                completedAt: '2025-10-09T14:30:00Z'
                durationMs: 1170
        '400':
          description: Bad request. Invalid tenant or credential ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have view tenants permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified tenant or credential does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResp

# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/controlup/refs/heads/main/openapi/controlup-tenants-api-openapi.yml