Skip to main content

​
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

Anything defined in the Ironclad API 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.
1

Open Company Settings

In Ironclad, click your user profile dropdown (top right) and select Company Settings.
2

Go to the API tab

Select the API tab in the left sidebar.
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.
3

Create the app

Click Create new app, give it a name (e.g. “Serval Integration”), and click Create app.
4

Save the Client ID and Client Secret

Copy both values immediately.
The Client Secret is shown only once - it is not retrievable after the modal closes. Store it somewhere safe before continuing.
5

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

Add scopes

Add the Requested Resource Scopes your automations need (for example public.workflows.read and public.records.read), then click Save Changes.
Write down the exact scope list - you’ll enter the same scopes in Serval, and they must match what the app grants.
7

Pick an admin user

Note the email address of the Ironclad admin user that Serval should make requests on behalf of.

​
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”).
1

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

Enter the Client ID

The OAuth 2.0 client ID from your Ironclad OAuth application (Company Settings > API > Create new app).
3

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

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”.
5

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.

​
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.”
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.

​
Gotchas and troubleshooting

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.
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.
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”.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Ironclad integration.