Configuration profiles API workflow documentation

The following content provides a detailed description of the API usage for creating, updating, and deleting configuration profiles in addition to configuring settings for it. For more details on configuration profiles as well as using the UI, please click here.

Note:

Some additional headers are required while making each of the following API calls. [1]

Step 1 : Creating a configuration profile record

Before we can configure settings for a configuration profile, first we need to create a configuration profile record which will contain all the necessary details to provide user group specific settings. We can do that by making the following API call.

• Type: POST
• URL: /aca/profile
• Description: Creates a new configuration profile record for the given URL.
• Parameters: postBody - Contains required attributes for configuration profile record creation. [2]
• Response: A JSON object containing details of a specific configuration profile. [3]

Note:

When creating a configuration profile record, it is possible to add up to 10 groups. Furthermore, a total of 20 configuration profiles can be created.

Step 2 : Fetching configuration profiles

Now that we have created a configuration profile record, we can retrieve the same using the following API calls.

2.1 : Fetching configuration profiles for a customer

• Type: GET
• URL: /aca/profile
• Description: Gets all the configuration profiles’ data for the given Customer ID.
• Response: A JSON object containing all configuration profile records for the customer. [4]

2.2 : Fetching configuration profiles for a specific url

• Type: GET
• URL: /aca/profile/url/{url}
• Description: Gets the configuration profile data for a given url.
• Parameters:
  • url - The specific URL in apt format (then base64 encoded). [5]
• Response: A JSON object containing all configuration profile records for a specific service URL owned by the customer. [4]

2.3 : Fetching data for a specific configuration profile ID

• Type: GET
• URL: /aca/profile/{profileId}
• Description: Gets the configuration profile data for a given configuration profile ID.
• Parameters:
  • profileId - The configuration profile ID to fetch data for.
• Response: A JSON object containing details of a given configuration profile. [3]

Step 3 : Managing settings for a configuration profile

After the creation of a configuration profile we can now assign settings to it which can be served to the user groups (subject to configuration profile priority resolution).

• Type: POST / PUT
• URL: /aca/settings/app/{app}/url
• Description: Creates (POST) or Updates (PUT) settings for a given configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to update.
  • url - The given service URL in apt format. [5]
  • Body - Contains settings to be configured, url, and configuration profile ID in the format below.

{
  "serviceURL": {
    "url": {serviceURL} // Add the serviceURL here
  },
  "settingsProfile": {
    "profileId": {configurationProfileID} // Add the configuration profile ID here
  },
  "settings": {
    "name": "Productivity Apps",
    "description": "Provides access to MS Office and other basic apps",
    "useForAppConfig": true,
    "appSettings": {
      "windows": [
        {
          "category": "root",
          "userOverride": false,
          "assignedTo": [
            "AllUsersNoAuthentication"
          ],
          "assignmentPriority": 0,
          "settings": [
            {
              "name": "Hide Local Keyboard Layout Setting",
              "value": "false"
            }
          ]
        }
      ]
    }
  }
}
<!--NeedCopy-->

Note:

Configuration profiles are currently only supported for Workspaces and are not supported with channels. For a complete list of settings that can be configured for a configuration profile, see this.

Step 4 : Updating a configuration profile record

Once a configuration profile is created, if we need to make modifications to any of its attributes, we can make use of the following API calls.

4.1 Updating a configuration profile record

• Type: PUT
• URL: /aca/profile/{profileId}
• Description: Updates the configuration profile record for a given configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to update.
  • putBody - Contains updated data. [2]
• Response: None

4.2 Adding groups to a configuration profile record

• Type: PATCH
• URL: /aca/profile/{profileId}/groups$add
• Description: Adds groups in a configuration profile record for a given configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to update.
  • patchBody - Contains groups to be added. [6]
• Response: JSON object containing updated configuration profile data.

4.3 Removing groups from a configuration profile record

• Type: PATCH
• URL: /aca/profile/{profileId}/groups$remove
• Description: Patches the group IDs in a configuration profile record to remove group IDs for a given configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to update.
  • patchBody - Contains the groups to be removed: [6]
• Response: JSON object containing updated configuration profile data.

4.4 Updating configuration profile priority

• Type: PATCH
• URL: /aca/profile/{profileId}/priority$replace
• Description: Updates priority in a configuration profile record for a given configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to update.
  • patchBody - Contains priority to be updated. [7]
• Response: JSON object containing updated configuration profile data.

Step 5 : Removing a configuration profile record

If we want to remove a configuration profile record, we can do that in the following two steps. First we need to remove the settings associated with that profile, then we can proceed to remove the configuration profile record.

Step 5.1 : Deleting settings for a configuration profile

• Type: DELETE
• URL: /aca/settings/app/${app}/url/{url}/profile/{profileId}
• Description: Deletes settings for a particular configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to update.
  • url - The given service URL in apt format. [5]
• Response: None

Step 5.2 : Removing configuration profile record

• Type: DELETE
• URL: /aca/profile/{profileId}
• Description: Deletes the configuration profile record for a given configuration profile ID.
• Parameters:
  • profileId - The given configuration profile ID to delete.
• Response: None

Footer

1. The following headers are mandatory for every API call

• Citrix-CustomerId : Citrix Cloud Customer ID.
• Citrix-TransactionId : Transaction ID (GUID) that is used to track this request.
• Authorization : CWSAuth bearer={bearerToken}

2. JSON body having required attributes for configuration profile creation or updation

{
  "description": "string",
  "groups": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "name": "string",
  "priority": number,
  "url": "string"
}
<!--NeedCopy-->

Groups can be queried by using the following command. Make sure to replace the values in curly braces.

curl --location --request POST 'https://cws.citrixworkspacesapi.net/{YOUR-CUSTOMER-ID}/users/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: CWSAuth bearer={token}' \
--data-raw '
{
    "adminUser": "",
    "domain": "{YOUR-DOMAIN}", // Use your domain for AD or null for AZUREAD
    "forest": "{YOUR-DOMAIN}", // Use your domain for AD or null for AZUREAD
    "idpType": "AD", // Use your IdP type, can be AD or AZUREAD
    "key": "",
    "query": "gacsadmin", // Use this query to search for groups
    "offerings": [],
    "supportsAzureAdGroups": false // Set this flag as true if you use AZUREAD
}'
<!--NeedCopy-->

A response to the above request would look like this.

{
    "results": [
        {
            "accountName": "gacsadmin", // Use accountName for AD as name
            ...
            "displayName": "gacsadministrator", // Use displayName for AAD as name
            ...
            "isGroup": true, // Consider records only which have isGroup as true
            ...
            "universalClaims": [
                "SID:/**********-*************", // Use SID prefix claim for AD as group Id
                "OID:/azuread/****************" // Use OID prefix claim for AAD as group Id
            ]
        }
    ]
}
<!--NeedCopy-->

Description of the attributes of the schemas

• description: string Providing a description of the configuration profile.
• groups: array of objects with the following properties.
  • id: string Active Directory or Azure Active Directory ID.
  • name: string Name of the configuration profile.
• name: string consisting of alphanumerics, spaces, ‘-‘ and ‘_’.
• priority: number between 1 and 1 million.
• url: string the service URL in apt format. [5]
• id: Configuration profile ID (GUID) of the created configuration profile record for example: 3fa81f64-5417-1562-b3fc-2c953f63afa6
• createdAt: Time of creation of configuration profile record for example: 2024-02-13T03:23:19.273
• modifiedAt: Time of last modification of configuration profile record for example: 2024-02-13T03:23:19.273Z

3. JSON response body for a single configuration profile record

{
  "createdAt": "string",
  "description": "string",
  "groups": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "id": "string",
  "modifiedAt": "string",
  "name": "string",
  "priority": number,
  "url": "string"
}
<!--NeedCopy-->

4. JSON response body containing multiple configuration profile records

{
  "count": number,
  "items": [
    {
      "createdAt": "string",
      "description": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "id": "string",
      "modifiedAt": "string",
      "name": "string",
      "priority": number,
      "url": "string"
    }
  ],
  "nextToken": "string"
}
<!--NeedCopy-->

5. All the URLs while making calls are in the following format

{protocol}://{domain}:{port}/{path}

• protocol might be http or https in case of StoreFront URLs
• protocol is always https in case of Workspace URLs
• path is not present in case of Workspace URLs
• path is optional in case of StoreFront URLs

6. JSON body containing groups

{
  "groups": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
<!--NeedCopy-->

7. JSON body containing updated priority

{
  "priority": 0
}
<!--NeedCopy-->

Supported settings in configuration profiles and their values

The following table lists the settings and the values that are accepted per platform in configuration profiles:

Platforms tab {.tabnav}

Windows

macOS

{}