> ## 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.

# Sana

> Connect Sana, the AI knowledge and learning platform, to Serval with an API client so workflows can manage users, groups, programs, courses, assignments, teamspaces, and reporting. Currently in beta.

## About Sana

Sana is an AI knowledge and learning platform. Serval connects to your Sana tenant using an API client (a client ID and secret) that you create inside Sana, plus your tenant domain (for example `acme.sana.ai`). Once connected, workflows can read and act on your learning data: people, the groups they belong to, the courses and programs they're enrolled in, and the reports that track completion. The Sana integration is currently in **beta**.

<Note>
  When you connect, you choose whether Serval has **read** access or **read and write** access. Read access covers everything that looks up or reports on Sana data. Read and write access is required for anything that changes Sana, such as creating a user, enrolling someone in a program, or marking a course complete. Pick read only if you want to be certain that no workflow can ever modify Sana.
</Note>

**Authentication**

Serval authenticates with a Sana API client: a client ID and a client secret created in Sana. Serval stores the secret encrypted and exchanges it for a short-lived access token each time it calls Sana, so the workflows you build never handle the secret directly and there is no long-lived token sitting in a workflow. Tokens are refreshed automatically before they expire.

**Data sync**

On demand only. Serval calls Sana at the moment a workflow step runs. There is no background sync, and the integration ships no pre-installed workflows.

## What the Sana integration enables

Workflows can work with the main areas of your Sana tenant:

| Capability  | Description                                                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Users       | Look up and manage people in Sana: create, update, and remove users, send or regenerate invitations, set a user's manager, and read the groups a user belongs to.                          |
| Groups      | Manage groups and their membership: create, update, and delete groups, add or remove members, and change a member's role. Groups are how course and program assignment is often organized. |
| Programs    | Manage structured learning programs: create, update, and delete them, and enroll or unenroll members.                                                                                      |
| Courses     | Manage courses: create and link courses, update them, and record progress such as marking a course completed or resetting it for a learner.                                                |
| Assignments | See what content is assigned to a person, and assign or unassign content to them.                                                                                                          |
| Paths       | Read the learning paths defined in your tenant.                                                                                                                                            |
| Teamspaces  | Manage teamspaces and their membership: create and delete teamspaces, and add or remove members.                                                                                           |
| Reporting   | Run reporting jobs to pull completion and engagement data out of Sana for use in the rest of Serval.                                                                                       |

<Note>
  Serval works with your tenant's learning and knowledge data. It doesn't configure single sign-on or identity-provider user provisioning for Sana, which are set up directly in your identity provider.
</Note>

## Get your credentials

You create an API client inside Sana and give Serval its client ID and secret. The API client's access in Sana determines what Serval can do, so create it with the scopes your workflows need.

<Steps>
  <Step title="Sign in to Sana as an administrator">
    Sign in to your Sana tenant with an account that can manage API clients.
  </Step>

  <Step title="Create an API client">
    Go to **Manage → API** in Sana and create a new API client. Grant it read access, or read and write access, to match how you plan to use it in Serval.
  </Step>

  <Step title="Copy the client ID and secret">
    Copy the client ID and client secret. Store the secret somewhere safe: you will paste it into Serval, and Sana may show it only once.
  </Step>

  <Step title="Note your tenant domain">
    Your tenant domain is the host you use to reach Sana, for example `acme.sana.ai`. You will enter this in Serval.
  </Step>
</Steps>

<Warning>
  Serval only connects to hosts under `sana.ai`. Enter your real tenant host (for example `acme.sana.ai`), not `sana.com`, which belongs to an unrelated company.
</Warning>

## Connect in Serval

Open your team workspace, go to **Integrations → Connect new**, choose **Sana**, and fill in the connect form. Every field is required.

<Steps>
  <Step title="Enter the Sana domain">
    Enter your tenant host without `https://`, for example `acme.sana.ai`. Serval tidies up a pasted address (it strips the scheme, any trailing slash, and any path).
  </Step>

  <Step title="Enter the Client ID">
    Paste the client ID from the API client you created in Sana.
  </Step>

  <Step title="Enter the Client secret">
    Paste the client secret. Serval stores it encrypted and only ever uses it to mint the short-lived tokens it needs to call Sana.
  </Step>

  <Step title="Choose Access">
    Choose **Read and write** (the default) or **Read only**. Write access is required for any workflow that changes Sana. Choose read only to guarantee that workflows can never modify your Sana data.
  </Step>

  <Step title="Submit the form">
    Submit to create the connection. Serval verifies it with a health check against your tenant.
  </Step>
</Steps>

## Verifying the connection

When you connect, Serval runs a check that confirms it can mint a token from your credentials and reach your tenant. The integration also includes four built-in health checks you can run at any time from the connection's **API Integration** tab:

| Check           | What it verifies                                                                          |
| --------------- | ----------------------------------------------------------------------------------------- |
| Test Connection | Confirms Serval can obtain a token from your client credentials and reach the tenant API. |
| List Users      | Confirms read access to user records.                                                     |
| List Groups     | Confirms read access to groups.                                                           |
| List Courses    | Confirms read access to courses.                                                          |

<Tip>
  If every check fails with valid-looking credentials, the most common cause is that the API client in Sana wasn't granted the access you chose in the connect form. Confirm the client's scopes in Sana, then rerun the checks.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Read versus read and write">
    The access you pick at connect time is enforced on every call. A connection created with read only can't create users, enroll people, or mark courses complete, even if a workflow asks it to. If a write action fails, check whether the connection (and the underlying Sana API client) has write access.
  </Accordion>

  <Accordion title="Use your real tenant host">
    Serval only reaches hosts under `sana.ai`, and the host you enter is where every request goes. Enter your tenant host (for example `acme.sana.ai`) without `https://`. Don't use `sana.com`, which belongs to an unrelated company.
  </Accordion>

  <Accordion title="The API client's access in Sana bounds what Serval can do">
    Serval can do exactly what the API client is allowed to do in Sana. If workflows hit permission errors while the connection looks healthy, widen the client's access in Sana (or create a new client with the scopes you need) and update the connection.
  </Accordion>

  <Accordion title="Beta integration">
    The Sana integration is marked beta in the connect screen. Behavior and available capabilities may change.
  </Accordion>
</AccordionGroup>

***

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