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

# Sigil

> Manage Sigil users, groups, and application access from Serval workflows.

## Connect Sigil

<Steps>
  <Step title="Sign in to Sigil Platform">
    Open [Sigil Platform](https://sigil.app/admin/platform/) and sign in as an administrator.
  </Step>

  <Step title="Create a credential">
    Open **Manage Credentials** and create a credential with the permissions your workflows need. Copy the secret when it is shown; Sigil displays it only once.
  </Step>

  <Step title="Connect Sigil in Serval">
    Add the **Sigil** integration in Serval and enter the **API Credential Secret**.
  </Step>

  <Step title="Run the health checks">
    Run **Validate API connection**, followed by the health checks for the resources your workflows use.
  </Step>
</Steps>

Serval stores the credential and injects it as a bearer token when calling `https://sigil.app/api`. Workflow code does not need the secret. The integration is marked Beta.

## Permissions

The connection check calls `/api/users/me`, which requires authentication without additional permissions. Other health checks verify access separately:

| Operation | Sigil permissions |
| - | - |
| Read users | Read Users |
| Create, update, or delete users | Read Users and Add or Modify Users |
| Read groups | Read Groups |
| Create, update, or delete groups | Read Groups and Add or Modify Groups |
| Read group memberships | Read Group Members |
| Add or remove group memberships | Read Group Members and Add or Modify Group Members |
| Read app configurations and effective access | Read Apps |

Grant write permissions only when your workflows need them. A connection can pass authentication while a resource health check fails because its credential lacks permission.

## Workflow operations

The **Sigil API request** action supports listing, creating, updating, and deleting users and groups; listing, adding, removing, and checking group membership; and reading apps and effective app access.

To grant application access, read the app's `assignmentGroupId` and add the user to that group. To revoke a direct assignment, remove the matching membership. Nested groups can also grant access: inspect `/api/apps/access` and its `groupPath` before concluding that removing a direct membership removed all access.

List endpoints use `limit` (maximum 1000), `offset`, and `total`. Increase `offset` by the number of returned records to read another page. Exact-match filters use `is:`; for example, `email: "is:person@example.com"` or `groupId: "is:<group UUID>"`.

<Warning>
  DELETE collection endpoints remove every matching record. Always supply filters identifying the
  intended user, group, or membership. An unfiltered DELETE can remove all records visible to the
  credential.
</Warning>

For PATCH requests, omit fields you want to preserve. Sending `null` clears a nullable field. Creating users, groups, and memberships requires a Sigil `tenantId`; membership creation also requires `groupId` and the appropriate `memberUserId` or `memberGroupId`.

This connector covers identity and application access. Device, session, audit-log, credential, token, tenant, and app-configuration administration are outside its current typed API.

## Rotate the credential

Create a replacement credential in Sigil, update the connection secret in Serval, and run the health checks before revoking the old credential. Leaving the secret unchanged or blank when editing preserves the stored credential.

A `401` indicates an invalid or expired credential. A `403` indicates a missing permission. The membership-check endpoint returns `404` when the user or group is not a member.


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