# Ironclad

Connect Ironclad so Suger AI can work with your contract workflows, records, and signatures.

---

## Overview

[Ironclad](https://ironcladapp.com) is a contract lifecycle management platform covering workflow-driven contract creation, approvals, signature, and a searchable repository. Connecting it lets the Suger AI agent drive contract workflows and read your records repository from a Suger workflow or chat.

### Org-Level vs User-Level

> **Org-Level**: Supported, using the OAuth 2.0 client-credentials grant against your own Ironclad environment.
>
> **User-Level**: Not currently available. Ironclad's OAuth client is registered inside your own account rather than centrally, so there is no single Suger app your users could sign in to.

### How the connection works

The OAuth client is registered in **your** Ironclad environment, not centrally by Suger. Suger exchanges its client ID and secret for an access token against your environment and refreshes it as needed. Ironclad also requires an acting user on every request, which is why the connect form asks for one.

```d2
shape: sequence_diagram
admin: "Your Suger admin"
ironclad: "Your Ironclad environment"
suger: "Suger"
agent: "Suger AI agent"
admin -> ironclad: "Register an OAuth client and grant it scopes"
admin -> suger: "Client ID + Secret, environment, acting-user email"
agent -> suger: "Run an Ironclad tool"
suger -> ironclad: "client_credentials grant at https://{environment}.ironcladapp.com"
ironclad -> suger: "Access token — Suger refreshes it" { style.stroke-dash: 4 }
suger -> ironclad: "API call, made on behalf of the acting user"
ironclad -> agent: "Result, bounded by the client scopes AND that user's permissions" { style.stroke-dash: 4 }
```

## Create Integration (Org-Level)

### Prerequisites

- An Ironclad account with API access.
- Permission to register an OAuth client (**Company Settings → API**).
- An Ironclad user whose identity Suger should act as. Ironclad requires an acting user on every API request, so this is not optional.
- The Suger **Admin** role — connecting, disconnecting, and running an integration's actions are all admin-only in Suger.

### Authenticate by client credentials

1. In Ironclad, register a new OAuth client and grant it the scopes you want Suger to have. Ironclad's scopes are per resource and action — for example `public.workflows.createWorkflows` — so a missing scope makes the matching tool fail. See [Register an OAuth client](https://developer.ironcladapp.com/reference/register-oauth-client).
2. Copy the **Client ID** and **Client Secret**.
3. In the Suger console, open [Settings → Integrations](https://console.suger.io/settings?tab=integrations) and click **Connect** on **Ironclad**.
4. Enter:
   - **Client ID** and **Client Secret** — from step 2.
   - **Environment** — `na1`, `demo`, or `eu1`, matching your Ironclad tenant.
   - **Acting user email** — the Ironclad user Suger makes requests on behalf of.
5. Save.

<!-- screenshot needed: the "Connect to Ironclad" dialog showing Client ID, Client Secret, Environment and Acting user email — BLOCKED: the Ironclad connector is provisioned by the deploy-time migration, so the dialog cannot be reached in a local dev environment on this branch -->

:::warning
**The acting user is fixed at connect time and applies to every request, for everyone in your organization.** Whatever that person can see and do in Ironclad is exactly what the Suger agent can see and do — so the choice either over-grants or under-grants unless it is deliberate. Use a **dedicated Ironclad integration user**, not a real employee's account: if that employee leaves or their permissions change, the integration silently changes behaviour or stops working.
:::

## Suger AI Tools

When Ironclad is connected, the Suger AI agent can drive contract workflows through Suger's built-in tools (46 actions).

> **Org-level**: Every tool runs as the **acting user** configured above, within the scopes granted to your OAuth client. A permission error means one or the other is too narrow.

| Capability | What the agent can do |
|------------|-----------------------|
| **Workflows** | Create a workflow (synchronously or async), read it, and list workflows; update its attributes (e.g. `create-workflow`, `create-workflow-async`, `update-workflow-attributes`) |
| **Workflow lifecycle** | Pause, resume, cancel, or revert a workflow to review (e.g. `pause-workflow`, `revert-to-review-workflow`) |
| **Approvals** | List a workflow's approvals and approval requests, and record a decision (e.g. `list-workflow-approvals`, `update-approval-status`) |
| **Signatures** | Send a signature request, check signing status, and list signatures (e.g. `send-signature-request`, `get-sign-status`) |
| **Documents** | List and download the documents attached to a workflow (`list-workflow-documents`, `download-workflow-document`) |
| **Comments & history** | Add and list workflow comments, and read participants and turn history (e.g. `create-workflow-comment`, `list-workflow-turn-history`) |
| **Schemas** | Read and list workflow schemas, and list eligible assignees (e.g. `get-workflow-schema`, `list-eligible-assignees`) |
| **Records** | Create, read, replace, rename, delete, and list repository records; read metadata, run a record action, and export to XLSX (e.g. `create-record`, `run-record-action`, `export-records-xlsx`) |
| **Entities** | Create, read, update, delete, and list entities, and read relationship types (e.g. `create-entity`, `list-entity-relationship-types`) |
| **Webhooks** | Create, read, update, delete, and list webhooks, and fetch the verification key (e.g. `create-webhook`, `get-webhook-verification-key`) |

:::tip
Open the integration from **Settings → Integrations** to see the exact tool list for your connection on its **Actions** tab, and to try a call on the **Playground** tab. The Playground pre-fills only the inputs an action *requires* — add optional ones yourself when you need them.
:::

## Edit Integration

Editing is not supported. To change the acting user, rotate the client secret, or switch environments, delete the integration and create it again.

## Delete Integration

Click the 🗑️ button next to **Ironclad** in the **Integrations** list. The stored client pair is destroyed with the integration record. Revoke the OAuth client in Ironclad too if you want to cut access from that side.