Developer Documentation

Managing Administrators

Getting started

May 23, 2024

Contributed by:

To use the Citrix Cloud administrators APIs, first create an API client and note the Citrix customer ID of the account.

Administrator IDs

For these APIs, “admin_id” or “id” may either be the administrator’s userId or the ucOid.

For User Administrators for all identity providers, use url-encoded userId.
For Group Administrators for all identity providers, use url-encoded ucOid.

Fetch administrators

Request

GET https://api.cloud.com/administrators
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

Response

{
  "items": [
    {
      "customerId": "acme",
      "ucOid": "OID:/citrix/0000000000000000000",
      "userId": "0000000000000000000",
      "type": "AdministratorUser",
      "accessType": "Full",
      "serviceProfile": null,
      "firstName": "Jenny",
      "lastName": "Rosen",
      "displayName": "Jenny Rosen",
      "email": "jenny.rosen@example.com",
      "providerType": "CitrixSts",
      "providerId": null,
      "providerProperties": null,
      "externalOid": null,
      "emailPreferences": "{\"SendNotificationEmails\":true,\"NotificationsSubscribed\":[{\"Type\":\"Error\",\"Enabled\":false},{\"Type\":\"Warning\",\"Enabled\":false},{\"Type\":\"Information\",\"Enabled\":false}],\"EnabledDate\":\"2023-01-26T21:00:08.1810121Z\"}",
      "notificationsEmailPreferences": {
        "sendNotificationEmails": true,
        "notificationsSubscribed": [
          {
            "type": "Error",
            "enabled": false
          },
          {
            "type": "Warning",
            "enabled": false
          },
          {
            "type": "Information",
            "enabled": false
          }
        ],
        "enabledDate": "2023-01-26T21:00:08.1810121Z"
      },
      "authDomain": null,
      "pending": false,
      "invitationExpired": null,
      "legacyProviders": null,
      "createdDate": "2018-08-09T15:17:46.6574164Z",
      "updatedDate": "2019-03-04T20:34:22.7930826Z",
      "eTag": null
    }
  ],
  "continuationToken": null
}
<!--NeedCopy-->

Get an administrator’s access

checkable.value indicates whether the permission is granted or not.

Request

GET https://api.cloud.com/administrators/{id}/access
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

Response

{
  "accessType": "Custom",
  "policies": [
    // DaaS permissions
    {
        "name": "R-3a45035c-a260-4b4a-88a9-64461cba5a",
        "serviceName": "XenDesktop",
        "displayName": "Cloud Administrator",
        "checkable": {
            "value": true,
            "canChangeValue": true
        },
        "scopeChoices": {
            "allScopesSelected": false,
            "choices": [
                {
                    "name": "XenDesktop-FullAdmin",
                    "displayName": "All",
                    "checkable": {
                        "value": false,
                        "canChangeValue": true
                    }
                }
            ]
        }
    },
    {
      "name": "R-ac0b54e3-6e8a-473f-9713-139218ed4e",
      "serviceName": "XenDesktop",
      "displayName": "Delivery Group Administrator",
      "checkable": {
          "value": true,
          "canChangeValue": true
      },
      "scopeChoices": {
          "allScopesSelected": false,
          "choices": [
              {
                  "name": "300adc84-286b-8cc4-29bd-36a0e7bb87b4",
                  "displayName": "Test scope",
                  "checkable": {
                      "value": true,
                      "canChangeValue": true
                  }
              }
          ]
      }
    },
    // ... other permissions
    {
      "name": "notifications",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "licensing",
      "serviceName": "Platform",
      "checkable": {
        "value": false,
        "canChangeValue": true
      }
    }
  ]
}
<!--NeedCopy-->

Add an administrator

The necessary parameters for adding a new administrator vary by the identity provider and administrator type (user, group) used.

Citrix identity provider

Adding a Citrix identity provider administrator will trigger an email invitation. The new administrator will be in a pending state until the invitation is accepted.

Note:

Citrix and AzureAd User Administrators that share the same email will be represented as a single administrator.

Request

POST https://api.cloud.com/administrators/$create
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

{
  "type": "AdministratorUser",
  "providerType": "CitrixSts",
  "accessType": "Full",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Roberts"
}
<!--NeedCopy-->

Response

{
  "accessType": "Full",
  "customerId": "<customer_id>",
  "displayName": "Alice Roberts",
  "email": "alice@example.com",
  "firstName": "Alice",
  "invitationExpired": false,
  "lastName": "Roberts",
  "pending": true,
  "providerId": "...",
  "providerType": "CitrixSts",
  "type": "AdministratorUser",
  "ucOid": "OID:/citrix/..."
}
<!--NeedCopy-->

Azure Active Directory

Azure Active Directory users or groups may be added as Citrix Cloud administrators.

Note:

Citrix and AzureAd User Administrators that share the same email will be represented as a single administrator document.

Request

POST https://api.cloud.com/administrators/$create
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

{
  "type": "AdministratorUser" | "AdministratorGroup",
  "providerType": "AzureAd",
  "accessType": "Custom",
  "externalProviderId": "...", // Azure AD tenant ID.
  "externalUserId": "...", // Azure AD user/group ID.
  "displayName": "Alice Roberts",

  // Include the following for Azure AD users (not groups).
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Roberts"
}
<!--NeedCopy-->

Response

{
  "accessType": "Custom",
  "customerId": "<customer_id>",
  "displayName": "Alice Roberts",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Roberts",
  "providerId": "...",
  "providerType": "AzureAd",
  "type": "AdministratorUser" | "AdministratorGroup",
  "ucOid": "OID:/azuread/..."
}
<!--NeedCopy-->

Google Cloud Identity

Google users or groups may be added as Citrix Cloud administrators.

Request

POST https://api.cloud.com/administrators/$create
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

{
  "type": "AdministratorUser" | "AdministratorGroup",
  "providerType": "Google",
  "accessType": "Custom",
  "externalProviderId": "...", // Google customer ID.
  "externalUserId": "...", // Google user/group ID.
  "displayName": "Alice Roberts",

  // Include the following for Google users (not groups).
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Roberts"
}
<!--NeedCopy-->

Response

{
  "accessType": "Custom",
  "customerId": "<customer_id>",
  "displayName": "Alice Roberts",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Roberts",
  "providerId": "...",
  "providerType": "Google",
  "type": "AdministratorUser" | "AdministratorGroup",
  "ucOid": "OID:/google/..."
}
<!--NeedCopy-->

SAML 2.0

Active Directory groups may be added as Citrix Cloud administrators through SAML 2.0.

Request

POST https://api.cloud.com/administrators/$create
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

{
  "type": "AdministratorGroup",
  "providerType": "Ad",
  "accessType": "Custom",
  "externalProviderId": "...", // AD tenant ID.
  "externalUserId": "...", // AD group ID.
  "displayName": "Group Display Name"
}
<!--NeedCopy-->

Response

{
  "accessType": "Custom",
  "customerId": "<customer_id>",
  "displayName": "Group Display Name",
  "providerId": "...",
  "providerType": "Ad",
  "type": "AdministratorGroup",
  "ucOid": "OID:/ad/..."
}
<!--NeedCopy-->

Update an administrator’s access

Administrators with Custom access may have their permissions changed. The below example demonstrates how to grant all general permissions to an administrator.

checkable.value indicates whether the permission is granted or not.
For accessType := "Full", set policies to null.

Request

PUT https://api.cloud.com/administrators/access?id=<admin_id>
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
Content-Type: application/json
<!--NeedCopy-->

{
  "accessType": "Custom",
  "policies": [
    {
      "name": "notifications",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "cloudLibrary",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "domains",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "customerDashboard",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "systemlog",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "workspaceConfiguration",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "resourceLocations",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "secureClients",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    },
    {
      "name": "licensing",
      "serviceName": "Platform",
      "checkable": {
        "value": true,
        "canChangeValue": true
      }
    }
  ]
}
<!--NeedCopy-->

Response

No response body.

Delete an administrator

Request

DELETE https://api.cloud.com/administrators/<admin_id>
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

Response

No respose body.

Delete a user administrator invitation

Request

DELETE https://api.cloud.com/administrators/invitations?email={email}
Accept: application/json
Authorization: CWSAuth bearer=<token>
Citrix-CustomerId: <customer_id>
<!--NeedCopy-->

Response

true if the removal was successful, otherwise false.

true
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Managing Administrators OpenAPI Specification

Copy Download

Getting started

May 23, 2024

Contributed by:

May 23, 2024

Contributed by:

Getting started

Administrator IDs

Fetch administrators

Request

Response

Get an administrator’s access

Request

Response

Add an administrator

Citrix identity provider

Request

Response

Azure Active Directory

Request

Response

Google Cloud Identity

Request

Response

SAML 2.0

Request

Response

Update an administrator’s access

Request

Response

Delete an administrator

Request

Response

Delete a user administrator invitation

Request

Response

Resources

Managing Administrators OpenAPI Specification

In this article

Resources

Managing Administrators OpenAPI Specification