> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Citrix Cloud

> Connect Serval to Citrix Cloud to manage Citrix DaaS sessions, machines, and delivery groups, query Monitor data, and read Citrix Cloud system logs and administrators.

## About Citrix Cloud

Citrix Cloud hosts Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) and its supporting platform APIs. Serval calls the Citrix Cloud REST APIs on your behalf whenever a Serval workflow runs.

**Authentication:** a Citrix Cloud **service principal** (Client ID and Client Secret) plus your **Customer ID**. Serval exchanges the service principal for a one-hour token at `https://<region host>/cctrustoauth2/<customer ID>/tokens/clients` and sends it on every request as `Authorization: CwsAuth Bearer=<token>` together with the `Citrix-CustomerId` header. Citrix DaaS and Monitor APIs reject the standard `Bearer <token>` format, so a generic OAuth connection can't reach them.

**Data sync:** on demand only. Serval reads from and writes to Citrix Cloud when a workflow runs.

## What the Citrix Cloud integration enables

| Capability | Endpoints |
| - | - |
| Discover your DaaS site | `GET /cvad/manage/me` returns your customers and their site IDs. |
| Manage sessions | List and search sessions (`POST /cvad/manage/Sessions/$search`), and disconnect (`POST /cvad/manage/Sessions/{id}/$disconnect`) or log off (`POST /cvad/manage/Sessions/{id}/$logoff`) a session. |
| Read DaaS inventory | List and get machine catalogs, delivery groups, machines, and published applications under `/cvad/manage`. Update a delivery group with `PATCH /cvad/manage/DeliveryGroups/{nameOrId}`. |
| Query Monitor data | OData queries against `/monitorodata/Users`, `Sessions`, `Machines`, `Connections`, and `ConnectionFailureLogs`, with `$filter`, `$select`, `$expand`, `$orderby`, and `$top`. |
| Audit Citrix Cloud | Read system log records (`/systemlog/records`), administrators (`/administrators`), and service principals (`/serviceprincipals`). |

## Installable workflows

The **Session Self-Service** bundle lets people manage their own Citrix DaaS sessions through Serval:

| Workflow | What it does | Default approval |
| - | - | - |
| List My Citrix Sessions | Lists the user's current sessions with each session's ID, state, machine, and delivery group. | None |
| Disconnect My Citrix Session | Disconnects one of the user's sessions. The session keeps running, so they can reconnect. | Installer approval |
| Log Off My Citrix Session | Logs the user off one of their sessions, closing its apps and discarding unsaved work. Citrix finishes the log-off in the background, so the result is `logged off`, `log-off in progress`, or `log-off requested`. | Installer approval |

Each workflow acts on its target user: the requester by default, or the person chosen when someone runs it on another user's behalf. It finds that user's Citrix account by matching their email to their UPN in Citrix Monitor, so the service principal needs to read Monitor data as well as DaaS sessions. Disconnect and log-off refuse any session that doesn't belong to the target user. If the connection can see more than one DaaS site, the workflows stop instead of guessing which site to use.

## Create a service principal

<Steps>
  <Step title="Open API Access">
    In Citrix Cloud, go to **Identity and Access Management** > **API Access**. Copy the **Customer ID** shown on this page.
  </Step>

  <Step title="Create the service principal">
    Open **Service principals** and create a new service principal. Give it the access your workflows need. For DaaS and Monitor, that means a Citrix DaaS administrator role (for example, a read-only role for reporting, or one with session and machine management for remediation).
  </Step>

  <Step title="Copy the credentials">
    Copy the service principal's **ID** (Client ID) and **Secret**. Citrix shows the secret only once.
  </Step>
</Steps>

<Warning>
  If the service principal has a network location allowlist, Citrix only issues tokens to allowed IP addresses. Contact [support@serval.com](mailto:support@serval.com) for Serval's egress IP addresses.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Choose the Region">
    **US, EU, or Asia Pacific South** (`api.cloud.com`) or **Japan** (`api.citrixcloud.jp`), matching the region your Citrix Cloud account is set to. Citrix Cloud Government isn't supported.
  </Step>

  <Step title="Enter the Customer ID">
    From **Identity and Access Management** > **API Access**.
  </Step>

  <Step title="Enter the Client ID and Client Secret">
    The service principal's ID and secret. The secret is stored encrypted and shown obfuscated when you edit the connection; leave it unchanged to keep the stored value.
  </Step>
</Steps>

## Verifying the connection

After saving, Serval runs these health checks:

* **Test Citrix Cloud Connection**: exchanges the credentials for a token and calls `GET /cvad/manage/me`.
* **List Citrix DaaS Delivery Groups**: reads the first DaaS site from `/cvad/manage/me` and lists its delivery groups, confirming the service principal has a DaaS role.
* **Query Citrix Monitor Sessions**: fetches one record from `/monitorodata/Sessions`.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Site-scoped DaaS calls need the site ID">
    Most `/cvad/manage` endpoints require the `Citrix-InstanceId` header. Get the site ID from `GET /cvad/manage/me` (`Customers[].Sites[].Id`) and pass it as `instanceId` to the Citrix Cloud API request action. `/cvad/manage/me` itself doesn't need it.
  </Accordion>

  <Accordion title="Session log-off is asynchronous">
    `POST /cvad/manage/Sessions/{id}/$logoff` returns a job. Poll `GET /cvad/manage/Jobs/{id}` to see when it finishes.
  </Accordion>

  <Accordion title="Access denied with valid credentials">
    If the health check authenticates but DaaS or Monitor calls return "Access denied", the service principal is missing the matching Citrix DaaS administrator role or scope.
  </Accordion>

  <Accordion title="Monitor results are paged">
    Monitor returns at most 1,000 records per page. Follow `@odata.nextLink` in the response to fetch more.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Citrix Cloud integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.