---
openapi: '3.0.1'

info:
  version: 1.0.0
  title: Administrators APIs
  description: APIs for managing CC administrators.
servers:
  - url: https://api.cloud.com/administrators
    description: For customers in Commercial citrix cloud
  - url: https://api.citrixcloud.jp/administrators
    description: For customers in JP region
paths:
  '/':
    get:
      operationId: FetchAdministrators
      tags:
        - Administrators
      summary: Fetch all CC administrators.
      parameters:
        - name: type
          in: query
          description: Optional administrator type filter.
          schema:
            maxLength: 256
            minLength: 0
            type: string
        - name: providerType
          in: query
          description: Optional provider type.
          schema:
            $ref: '#/components/schemas/AdministratorProviderType'
        - name: maxItemCount
          in: query
          description: Optional item count.
          schema:
            maxLength: 256
            minLength: 0
            pattern: ^[0-9]+$
            type: string
        - name: requestContinuation
          in: query
          description: Optional continuation token.
          schema:
            maxLength: 8192
            minLength: 0
            type: string
        - name: id
          in: query
          description: >-
            User ID corresponding to a user administrator. (Note: Exclusive with other parameters on this endpoint.)
          schema:
            maxLength: 100
            minLength: 0
            type: string
        - name: Authorization
          in: header
          description: Access token.
          required: true
          schema:
            type: string
        - name: Citrix-CustomerId
          in: header
          description: Customer ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministratorsResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  '/{id}/access':
    get:
      operationId: GetAdministratorAccess
      tags:
        - Administrators
      summary: Fetch the access of an administrator.
      parameters:
        - name: id
          in: path
          description: UserId for AzureAd and Citrix User Administrators. UcOid for all others.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministratorAccessModel'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  '/$create':
    post:
      operationId: CreateAdministrator
      tags:
        - Administrators
      summary: Create a new CC administrator.
      parameters:
        - name: Authorization
          in: header
          description: Access token.
          required: true
          schema:
            type: string
        - name: Citrix-CustomerId
          in: header
          description: Customer ID.
          required: true
          schema:
            type: string
      requestBody:
        description: Administrator to be added.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdministratorInputModel'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministratorResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  '/access':
    put:
      operationId: UpdateAdministratorAccess
      tags:
        - Administrators
      summary: Update roles and permissions of an existing CC administrator.
      parameters:
        - name: id
          in: query
          description: CC administrator ID.
          required: true
          schema:
            maxLength: 100
            minLength: 0
            type: string
        - name: Authorization
          in: header
          description: Access token.
          required: true
          schema:
            type: string
        - name: Citrix-CustomerId
          in: header
          description: Customer ID.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdministratorAccessModel'
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  '/{id}':
    delete:
      operationId: DeleteAdministrator
      tags:
        - Administrators
      summary: Remove a CC administrator.
      parameters:
        - name: id
          in: path
          description: CC administrator ID.
          required: true
          schema:
            maxLength: 100
            minLength: 0
            type: string
        - name: Authorization
          in: header
          description: Access token.
          required: true
          schema:
            type: string
        - name: Citrix-CustomerId
          in: header
          description: Customer ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  '/invitations':
    delete:
      operationId: DeleteInvitation
      tags:
        - Administrators
      summary: Remove a CC pending user administrator invitation.
      parameters:
        - name: email
          in: query
          description: Pending user administrator invitation email.
          required: true
          schema:
            maxLength: 256
            minLength: 0
            type: string
            format: email
        - name: Authorization
          in: header
          description: Access token.
          required: true
          schema:
            type: string
        - name: Citrix-CustomerId
          in: header
          description: Customer ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden

components:
  schemas:
    AdministratorAccessModel:
      required:
        - accessType
      type: object
      properties:
        accessType:
          $ref: '#/components/schemas/AdministratorAccessType'
        policies:
          type: array
          items:
            $ref: '#/components/schemas/AdministratorAccessPolicyModel'
          nullable: true
    AdministratorAccessPolicyModel:
      required:
        - checkable
        - name
        - serviceName
      type: object
      properties:
        name:
          minLength: 1
          pattern: ^[a-zA-Z0-9_\-]{1,36}$
          type: string
          example: notifications
        serviceName:
          minLength: 1
          pattern: ^[a-zA-Z0-9_\-]{1,36}$
          type: string
          example: Platform
        displayName:
          maxLength: 256
          minLength: 0
          type: string
          nullable: true
        checkable:
          $ref: '#/components/schemas/BooleanPolicyProperty'
        scopeChoices:
          $ref: '#/components/schemas/AdministratorAccessScopeChoices'
    AdministratorAccessScopeChoices:
      type: object
      properties:
        allScopesSelected:
          type: boolean
        choices:
          type: array
          items:
            $ref: '#/components/schemas/AdministratorAccessScopeChoicesModel'
          nullable: true
          example: null
    AdministratorAccessScopeChoicesModel:
      required:
        - checkable
        - name
      type: object
      properties:
        name:
          minLength: 1
          pattern: ^[a-zA-Z0-9_\-]{1,36}$
          type: string
        displayName:
          maxLength: 256
          minLength: 0
          type: string
          nullable: true
        checkable:
          $ref: '#/components/schemas/BooleanPolicyProperty'
    AdministratorType:
      enum:
        - AdministratorUser
        - AdministratorGroup
        - ServicePrincipal
      type: string
    AdministratorAccessType:
      enum:
        - Full
        - Custom
        - Reinvite
      type: string
    AdministratorExternalProviderType:
      enum:
        - AzureAd
        - Ad
        - Okta
        - Google
      type: string
    AdministratorNotification:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AdministratorNotificationType'
        enabled:
          type: boolean
          nullable: true
    AdministratorNotificationType:
      enum:
        - Error
        - Warning
        - Information
        - Critical
      type: string
    AdministratorNotificationsEmailsPreferences:
      required:
        - sendNotificationEmails
      type: object
      properties:
        sendNotificationEmails:
          type: boolean
        notificationsSubscribed:
          type: array
          items:
            $ref: '#/components/schemas/AdministratorNotification'
          nullable: true
        enabledDate:
          type: string
          format: date
          nullable: true
    AdministratorProviderType:
      enum:
        - Ad
        - AzureAd
        - CitrixSts
        - Google
      type: string
    AdministratorResult:
      type: object
      properties:
        customerId:
          type: string
          nullable: true
        ucOid:
          type: string
          nullable: true
        userId:
          type: string
          nullable: true
        type:
          $ref: '#/components/schemas/AdministratorType'
        accessType:
          $ref: '#/components/schemas/AdministratorAccessType'
        serviceProfile:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
        firstName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
        lastName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
        displayName:
          maxLength: 256
          minLength: 0
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        providerType:
          $ref: '#/components/schemas/AdministratorProviderType'
        providerId:
          type: string
          nullable: true
        providerProperties:
          type: object
          properties:
            displayName:
              type: string
              nullable: true
            tid:
              type: string
              nullable: true
          nullable: true
        externalOid:
          type: string
          nullable: true
        emailPreferences:
          type: string
          nullable: true
        notificationsEmailPreferences:
          $ref: '#/components/schemas/AdministratorNotificationsEmailsPreferences'
        authDomain:
          type: string
          nullable: true
        pending:
          type: boolean
          nullable: true
        invitationExpired:
          type: boolean
          nullable: true
        legacyProviders:
          type: array
          items:
            type: string
          nullable: true
        createdDate:
          type: string
          format: date-time
          nullable: true
        updatedDate:
          type: string
          format: date-time
          nullable: true
        eTag:
          type: string
          nullable: true
      additionalProperties: {}
    AdministratorsResult:
      type: object
      properties:
        continuationToken:
          maxLength: 8192
          minLength: 0
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdministratorResult'
          nullable: true
    BooleanPolicyProperty:
      type: object
      properties:
        value:
          type: boolean
        canChangeValue:
          type: boolean
    CreateAdministratorInputModel:
      required:
        - accessType
        - providerType
        - type
      type: object
      properties:
        accessType:
          $ref: '#/components/schemas/AdministratorAccessType'
        displayName:
          maxLength: 256
          minLength: 0
          pattern: ^[^<>\:\/\\]*$
          type: string
          nullable: true
          example: Jenny Rosen
        email:
          type: string
          format: email
          nullable: true
        externalProviderId:
          maxLength: 8192
          minLength: 0
          type: string
        externalUserId:
          maxLength: 8192
          minLength: 0
          type: string
        firstName:
          maxLength: 256
          minLength: 0
          pattern: ^[^<>\:\/\\]*$
          type: string
          nullable: true
          example: Jenny
        lastName:
          maxLength: 256
          minLength: 0
          pattern: ^[^<>\:\/\\]*$
          type: string
          nullable: true
          example: Rosen
        policies:
          type: array
          items:
            $ref: '#/components/schemas/AdministratorAccessPolicyModel'
          nullable: true
        providerType:
          $ref: '#/components/schemas/AdministratorProviderType'
        type:
          minLength: 1
          type: string
    EmbargoedPersonId:
      type: object
      properties:
        embargoed:
          type: boolean
          nullable: true
        personId:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
    PendingAdministratorInvite:
      required:
        - email
      type: object
      properties:
        email:
          minLength: 1
          type: string
          format: email
        requestorEmail:
          type: string
          format: email
          nullable: true
        firstName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
          example: Jenny
        lastName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
          example: Rosen
        access:
          $ref: '#/components/schemas/AdministratorAccessModel'
    PendingAdministratorInviteExternal:
      required:
        - email
        - externalProviderId
        - externalProviderType
        - externalUserId
      type: object
      properties:
        email:
          minLength: 1
          type: string
          format: email
        requestorEmail:
          type: string
          format: email
          nullable: true
        firstName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
        lastName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
        access:
          $ref: '#/components/schemas/AdministratorAccessModel'
        displayName:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
        externalProviderType:
          $ref: '#/components/schemas/AdministratorExternalProviderType'
        externalProviderId:
          maxLength: 100
          minLength: 0
          type: string
        externalUserId:
          maxLength: 100
          minLength: 0
          type: string
        externalProviderProperties:
          type: object
          additionalProperties: {}
          nullable: true
        externalProviderAuthDomain:
          maxLength: 100
          minLength: 0
          type: string
          nullable: true
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
