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

# Ironclad

> Connect Serval to Ironclad, a contract lifecycle management platform, to read contract workflows, track approvals and signatures, add comments, and search records on demand.

## About Ironclad

Ironclad is a contract lifecycle management (CLM) platform that covers contract creation, negotiation, approvals, signatures, and records. Serval connects to your Ironclad account with an OAuth 2.0 client-credentials app and the email of an Ironclad admin user, then calls Ironclad's public REST API on your behalf. Every request Serval makes is performed as a specific Ironclad user - either the person a workflow run is acting for, or your configured admin as the fallback. Note that in Ironclad, a "workflow" is a *contract* workflow (approvals, signatures) - not a Serval workflow.

**Authentication:** OAuth 2.0 client credentials (Client ID + Client Secret from an Ironclad OAuth app), plus an Admin Email used to impersonate a user on each request.

**Data sync:** On-demand only - there is no background sync or scheduled ingestion. Serval reads from and writes to Ironclad at the moment a Serval workflow runs.

## What the Ironclad integration enables

| Capability                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read contract workflows               | Shipped Serval workflows "List All Workflows", "Get Workflow by ID", and "Get Workflow by Title" retrieve Ironclad contract workflows with complete metadata - all of them with pagination, one by its ID or Ironclad ID, or one by its exact title.                                                                                                                                                                                                                                |
| Track approvals and signatures        | "Get Workflow Approvals" retrieves all approvals for a specific contract workflow. "Get Workflow Sign Status" retrieves the signature step status for a workflow.                                                                                                                                                                                                                                                                                                                   |
| Comment on contract workflows         | "Add Workflow Comment" posts a comment to a contract workflow's activity feed, with support for user mentions.                                                                                                                                                                                                                                                                                                                                                                      |
| Search by counterparty                | "Search Workflows by Counterparty" finds every contract workflow associated with a counterparty company name. "Search Records by Counterparty" finds Ironclad records by counterparty name and generates signed copy URLs.                                                                                                                                                                                                                                                          |
| Call any Ironclad public API endpoint | A generic, typed API request action exposes the full Ironclad Public API: contract workflows (list, launch, retrieve, approvals, approval requests, turn history, signers, participants, revert to review, comments, metadata updates, documents, email threads and attachments), records (create, retrieve, replace, update, delete, attachments, XLSX export, smart import), workflow schemas, and webhooks. It can optionally impersonate a different Ironclad user per request. |

Anything defined in the [Ironclad API](https://developer.ironcladapp.com/reference) can be accessed through Serval.

## Get your credentials

Serval authenticates with an OAuth 2.0 client application that you create inside Ironclad, using the **Client Credentials** grant. You'll also need the email address of an Ironclad admin user (or an admin-privileged service account) that Serval will make requests on behalf of. Ironclad's official guide is here: [Ironclad client credentials grant](https://developer.ironcladapp.com/reference/client-credentials-grant).

<Steps>
  <Step title="Open Company Settings">
    In Ironclad, click your user profile dropdown (top right) and select **Company Settings**.
  </Step>

  <Step title="Go to the API tab">
    Select the **API** tab in the left sidebar.

    <Note>
      The API tab is only visible if the API add-on is enabled for your Ironclad instance. If you don't see it, contact your Ironclad representative.
    </Note>
  </Step>

  <Step title="Create the app">
    Click **Create new app**, give it a name (e.g. "Serval Integration"), and click **Create app**.
  </Step>

  <Step title="Save the Client ID and Client Secret">
    Copy both values immediately.

    <Warning>
      The Client Secret is shown only once - it is not retrievable after the modal closes. Store it somewhere safe before continuing.
    </Warning>
  </Step>

  <Step title="Set the grant type">
    In the app's settings, under **Grant Types**, select only **Client Credentials** (do not enable Authorization Code). Leave Redirect URIs blank.
  </Step>

  <Step title="Add scopes">
    Add the **Requested Resource Scopes** your automations need (for example `public.workflows.read` and `public.records.read`), then click **Save Changes**.

    <Tip>
      Write down the exact scope list - you'll enter the same scopes in Serval, and they must match what the app grants.
    </Tip>
  </Step>

  <Step title="Pick an admin user">
    Note the email address of the Ironclad admin user that Serval should make requests on behalf of.
  </Step>
</Steps>

## Connect in Serval

All five fields are required - the form flags any required field left blank with "This field is required" and won't save until it's filled. If an incomplete configuration reaches Serval's backend anyway, it is rejected with a message that begins "Invalid Ironclad configuration" (for example, "client ID is required", "client secret is required", or "scopes are required").

<Steps>
  <Step title="Enter the API Base URL">
    Your Ironclad domain, entered **without** `https://` or any path: `na1.ironcladapp.com` (US Production), `eu1.ironcladapp.com` (EU Production), `demo.ironcladapp.com` (Demo), or `preview.ironcladapp.com` (Preview). Anything that isn't an Ironclad domain is rejected with "Must be a valid Ironclad API base URL (e.g., na1.ironcladapp.com, eu1.ironcladapp.com)". This domain is also used for OAuth authentication, so it must match the environment where you created the app.
  </Step>

  <Step title="Enter the Client ID">
    The OAuth 2.0 client ID from your Ironclad OAuth application (Company Settings > API > Create new app).
  </Step>

  <Step title="Enter the Client Secret">
    The OAuth 2.0 client secret from the same app. It is stored encrypted and is required when you first connect. When editing the connection later, the secret appears obfuscated - leave it unchanged to keep the previously stored secret.
  </Step>

  <Step title="Enter the Admin Email">
    The email address of an admin user in Ironclad (e.g. `admin@company.com`). API requests are made on behalf of this user when a workflow run doesn't specify someone else. Invalid input shows "Must be a valid email address".
  </Step>

  <Step title="Enter the Scopes">
    A comma-separated list of OAuth scopes, e.g. `public.workflows.read, public.workflows.write, public.records.read`. At least one scope is required, and the list must match the scopes granted on your Ironclad OAuth app.
  </Step>
</Steps>

## Verifying the connection

After saving, Serval runs one health check:

**Test Ironclad Connection** - verifies the integration is properly configured and can authenticate. Serval performs the full OAuth client-credentials token exchange with your scopes, then requests a single contract workflow from Ironclad as your configured Admin Email.

* On success: "Successfully authenticated with Ironclad"
* On failure: "Unable to connect to Ironclad. Please verify your Client ID, Client Secret, and Admin Email are valid."

<Tip>
  A green test but failing automations usually means a per-user permission gap: the health check runs as your Admin Email, but Serval's shipped Ironclad workflows impersonate the workflow run's target user. If that person isn't a real Ironclad user or lacks permission to see the contract in question, their requests fail even though the connection test passes.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="'Workflows' means contract workflows, not Serval workflows">
    Throughout the Ironclad API and this integration, a "workflow" is an Ironclad contract workflow (approvals, signatures, turn history) - not a Serval automation workflow. Keep the two concepts separate when naming and reading automations.
  </Accordion>

  <Accordion title="Scopes must match the OAuth app exactly">
    The scopes you enter in Serval are sent verbatim with every token request. If they don't match what the Ironclad OAuth app actually grants, the token exchange fails ("failed to get OAuth token") and requests are rejected. When you change scopes, update both the Ironclad app and the Serval connection together.
  </Accordion>

  <Accordion title="Admin Email is required, and every request impersonates a user">
    Admin Email is required by both the connection form and Serval's backend validation. Every API call is made on behalf of an Ironclad user: shipped workflows pass the run's target-user email, and the Admin Email is the fallback when none is set. Requests are scoped to the impersonated user's Ironclad permissions, so the Admin Email must belong to a real Ironclad user with sufficient access. If neither value is present, the request fails with "admin email or x-as-user-email is required".
  </Accordion>

  <Accordion title="API Base URL is strictly validated and drives authentication">
    Only `na1.ironcladapp.com`, `eu1.ironcladapp.com`, `demo.ironcladapp.com`, `preview.ironcladapp.com`, or bare `ironcladapp.com` are accepted - without `https://` or a trailing path. The same domain is used to reach Ironclad's OAuth token endpoint and is enforced by Serval's outbound request allow-list, so an environment mismatch breaks both authentication and API calls.
  </Accordion>

  <Accordion title="Ironclad environments are isolated">
    An OAuth app created in one Ironclad environment (NA production, EU production, demo, preview) cannot be used in another. Create a separate OAuth app per environment and a separate Serval connection for each.
  </Accordion>

  <Accordion title="Don't include the API prefix in request paths">
    For teams building custom automations: Serval automatically adds Ironclad's `/public/api/v1` prefix to every request made through the generic API request action, so enter request paths without it. Including the prefix yourself produces a doubled path and a not-found error from Ironclad. A few operations (such as a workflow's signature-step status) are not part of the bundled API specification; they're still reachable through the generic action, just without type checking.
  </Accordion>

  <Accordion title="Client Secret is write-only after saving">
    On the connection's edit form the secret is shown obfuscated; leaving it unchanged preserves the stored secret while your other field edits are saved over the existing values. And remember Ironclad only shows the secret once at app creation - capture it before closing the modal.
  </Accordion>
</AccordionGroup>

***

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