A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Ironclad API is how an app or AI agent works with an Ironclad account: launching a contract workflow, advancing it through approval and signature, reading the records of completed contracts, and updating their metadata. Access is granted through an OAuth 2.0 token, and each method names the scope it needs, so a token reaches only the areas and actions it was granted. Ironclad can also push an event when a workflow or contract changes, so an integration learns about activity without polling.
How an app or AI agent connects to Ironclad determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes contract search to agents, and each is governed by the token behind it and the permissions that token carries.
The public REST API serves JSON over HTTPS under the v1 path, at a regional host such as https://na1.ironcladapp.com/public/api/v1 for North America or an eu1 host for Europe. A call authenticates with a Bearer token issued by OAuth 2.0, and each method names the OAuth scope it requires. List methods page through results.
Ironclad POSTs an event to a registered HTTPS URL when a workflow or contract changes, for event types like workflow_launched, workflow_completed, workflow_approval_status_changed, and contract_status_changed, or a wildcard for all of them. The receiver verifies the request against the webhook verification key before trusting it.
Ironclad publishes a hosted Model Context Protocol server that exposes its Conversational Search to AI clients, letting an agent run natural-language searches over contracts using the same engine as the dashboard. It is read-only, never creates, edits, or deletes data, and returns only results the signed-in Ironclad user is authorized to access. Claude clients are the officially supported clients.
The authorization code grant has a user sign in and consent, then issues a Bearer token tied to that user. The token acts with that user's permissions in Ironclad, on top of the OAuth scopes it was granted. This is the route for an integration acting on behalf of a specific person.
The client credentials grant lets an app obtain a Bearer token on its own, with no interactive sign-in. A request made with such a token must add an x-as-user-id or x-as-user-email header to name the acting user, so the call runs with that user's permissions. This is the route for a backend service or autonomous agent.
A static access token, generated in Ironclad, sent as a Bearer token. It was deprecated in November 2024 in favour of OAuth 2.0; existing integrations keep working for now, but new integrations should use OAuth 2.0 because the legacy token is slated to be disabled.
The Ironclad API is split into areas an agent can act on, like the workflows that move a contract through approval and signature, the records that hold completed contracts, and the schemas that describe their fields. Each area has its own methods, and writes in some areas advance a real contract, change its metadata, or send it for signature.
Methods for launching and reading contract workflows and their schemas.
Methods that advance a workflow: approvals, pause, resume, cancel, revert, and signature.
Methods for working with the records of completed contracts and their schema.
Methods for downloading the documents attached to a workflow.
Methods for registering, listing, and removing event subscriptions.
Methods for reading the users in an Ironclad account, provided through SCIM.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
WorkflowsMethods for launching and reading contract workflows and their schemas.6 | ||||||
| GET | /workflows | List all workflows in the account. | read | workflows.readWorkflows | Current | |
Full scope: public.workflows.readWorkflows. Reads are rate-limited to 400 requests per minute per account. Acts onworkflow Permission (capability) workflows.readWorkflowsVersionAvailable since the API’s base version Webhook eventNone Rate limit400/min (GET workflows) SourceOfficial documentation ↗ | ||||||
| GET | /workflows/{id} | Retrieve the data associated with a specific workflow. | read | workflows.readWorkflows | Current | |
Full scope: public.workflows.readWorkflows. Acts onworkflow Permission (capability) workflows.readWorkflowsVersionAvailable since the API’s base version Webhook eventNone Rate limit400/min (GET workflows) SourceOfficial documentation ↗ | ||||||
| POST | /workflows | Launch a new workflow synchronously to start a contract process. | write | workflows.createWorkflows | Current | |
Full scope: public.workflows.createWorkflows. Writes are rate-limited to 40 requests per minute per account. Acts onworkflow Permission (capability) workflows.createWorkflowsVersionAvailable since the API’s base version Webhook event workflow_launchedRate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| PATCH | /workflows/{id}/attributes | Update a workflow's metadata while it is in the Review step. | write | workflows.updateWorkflows | Current | |
Uses 'set' to add or change values and 'remove' to clear fields. Full scope: public.workflows.updateWorkflows. Acts onworkflow Permission (capability) workflows.updateWorkflowsVersionAvailable since the API’s base version Webhook event workflow_updatedRate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| GET | /workflow-schemas | List all workflow schemas, which define the fields a workflow type carries. | read | workflows.readSchemas | Current | |
Full scope: public.workflows.readSchemas. Acts onworkflow_schema Permission (capability) workflows.readSchemasVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflow-schemas/{id} | Retrieve a single workflow schema by id. | read | workflows.readSchemas | Current | |
Full scope: public.workflows.readSchemas. Acts onworkflow_schema Permission (capability) workflows.readSchemasVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workflow actionsMethods that advance a workflow: approvals, pause, resume, cancel, revert, and signature.8 | ||||||
| GET | /workflows/{id}/approvals | List all approvals on a workflow. | read | workflows.readApprovals | Current | |
Full scope: public.workflows.readApprovals. Acts onapproval Permission (capability) workflows.readApprovalsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflows/{id}/approval-requests | Retrieve the approval requests on a workflow. | read | workflows.readApprovals | Current | |
Full scope: public.workflows.readApprovals. Acts onapproval_request Permission (capability) workflows.readApprovalsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /workflows/{id}/approvals/{roleId} | Update the approval status for an approver role on a workflow. | write | workflows.updateApprovals | Current | |
Full scope: public.workflows.updateApprovals. Approving advances the contract. Acts onapproval Permission (capability) workflows.updateApprovalsVersionAvailable since the API’s base version Webhook event workflow_approval_status_changedRate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| POST | /workflows/{id}/pause | Pause an active workflow. | write | workflows.pause | Current | |
Full scope: public.workflows.pause. Acts onworkflow Permission (capability) workflows.pauseVersionAvailable since the API’s base version Webhook event workflow_pausedRate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| POST | /workflows/{id}/resume | Resume a paused workflow. | write | workflows.resume | Current | |
Full scope: public.workflows.resume. Acts onworkflow Permission (capability) workflows.resumeVersionAvailable since the API’s base version Webhook event workflow_resumedRate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| POST | /workflows/{id}/cancel | Cancel a workflow, with a required comment message. | write | workflows.cancel | Current | |
Full scope: public.workflows.cancel. Ends the contract process. Acts onworkflow Permission (capability) workflows.cancelVersionAvailable since the API’s base version Webhook event workflow_cancelledRate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| PATCH | /workflows/{id}/revert-to-review | Revert a workflow back to the Review step. | write | workflows.revertToReview | Current | |
Full scope: public.workflows.revertToReview. Acts onworkflow Permission (capability) workflows.revertToReviewVersionAvailable since the API’s base version Webhook eventNone Rate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
| POST | /workflows/{id}/sign-status/send-signature-request | Send a workflow's signature packet out for signature. | write | workflows.sendSignature | Current | |
Full scope: public.workflows.sendSignatureRequests. Sends a real signature request to signers. Acts onsignature_request Permission (capability) workflows.sendSignatureVersionAvailable since the API’s base version Webhook eventNone Rate limit40/min (POST/PATCH workflows) SourceOfficial documentation ↗ | ||||||
RecordsMethods for working with the records of completed contracts and their schema.6 | ||||||
| GET | /records | List all contract records in the repository. | read | records.readRecords | Current | |
Full scope: public.records.readRecords. Reads are rate-limited to 600 requests per minute per account. Acts onrecord Permission (capability) records.readRecordsVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (GET records) SourceOfficial documentation ↗ | ||||||
| GET | /records/{id} | Retrieve a single contract record. | read | records.readRecords | Current | |
Full scope: public.records.readRecords. Acts onrecord Permission (capability) records.readRecordsVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (GET records) SourceOfficial documentation ↗ | ||||||
| POST | /records | Create a contract record by specifying its metadata properties. | write | records.createRecords | Current | |
Full scope: public.records.createRecords. Writes are rate-limited to 200 requests per minute per account. Acts onrecord Permission (capability) records.createRecordsVersionAvailable since the API’s base version Webhook eventNone Rate limit200/min (POST/PATCH records) SourceOfficial documentation ↗ | ||||||
| PATCH | /records/{id} | Update a contract record's metadata. | write | records.updateRecords | Current | |
Full scope: public.records.updateRecords. Acts onrecord Permission (capability) records.updateRecordsVersionAvailable since the API’s base version Webhook event contract_status_changedRate limit200/min (POST/PATCH records) SourceOfficial documentation ↗ | ||||||
| GET | /records/metadata | Retrieve the records schema, including record types and metadata properties. | read | records.readSchemas | Current | |
Full scope: public.records.readSchemas. Acts onrecord_schema Permission (capability) records.readSchemasVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (GET records) SourceOfficial documentation ↗ | ||||||
| POST | /records/{id}/actions | Run a contract action on a record, like a configured status change. | write | records.applyAction | Current | |
Full scope: public.records.applyContractAction. Acts onrecord Permission (capability) records.applyActionVersionAvailable since the API’s base version Webhook event contract_status_changedRate limit200/min (POST/PATCH records) SourceOfficial documentation ↗ | ||||||
DocumentsMethods for downloading the documents attached to a workflow.1 | ||||||
| GET | /workflows/{id}/document/{key}/download | Download a document attached to a workflow. | read | workflows.readDocuments | Current | |
Full scope: public.workflows.readDocuments. Returns the document contents. Acts ondocument Permission (capability) workflows.readDocumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for registering, listing, and removing event subscriptions.3 | ||||||
| POST | /webhooks | Create a webhook subscription for a set of event types. | write | webhooks.createWebhooks | Current | |
Full scope: public.webhooks.createWebhooks. Webhook methods are rate-limited to 600 requests per minute per account. Acts onwebhook Permission (capability) webhooks.createWebhooksVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (webhooks) SourceOfficial documentation ↗ | ||||||
| GET | /webhooks | List all webhook subscriptions. | read | webhooks.readWebhooks | Current | |
Full scope: public.webhooks.readWebhooks. Acts onwebhook Permission (capability) webhooks.readWebhooksVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (webhooks) SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/{id} | Delete a webhook subscription. | write | webhooks.deleteWebhooks | Current | |
Full scope: public.webhooks.deleteWebhooks. Stops event delivery to that endpoint. Acts onwebhook Permission (capability) webhooks.deleteWebhooksVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (webhooks) SourceOfficial documentation ↗ | ||||||
Users (SCIM)Methods for reading the users in an Ironclad account, provided through SCIM.2 | ||||||
| GET | /Users | List all users in the account, provided through SCIM. | read | scim.users.readUsers | Current | |
SCIM 2.0 surface, on its own base path, not the public/api/v1 path. Scope: scim.users.readUsers. Acts onuser Permission (capability) scim.users.readUsersVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (SCIM users GET) SourceOfficial documentation ↗ | ||||||
| GET | /Users/{userId} | Retrieve a single user by id, provided through SCIM. | read | scim.users.readUsers | Current | |
SCIM 2.0 surface, on its own base path. Scope: scim.users.readUsers. Acts onuser Permission (capability) scim.users.readUsersVersionAvailable since the API’s base version Webhook eventNone Rate limit600/min (SCIM users GET) SourceOfficial documentation ↗ | ||||||
Ironclad can notify an app when something happens to a workflow or a contract, like a workflow launching, an approval changing, a document being signed, or a contract's status changing. It POSTs an event describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
workflow_launched | Fires each time a workflow is launched, the start of a contract moving through Ironclad. | /workflows |
workflow_updated | Fires each time a workflow has been updated, including changes to its metadata. | /workflows/{id}/attributes |
workflow_completed | Fires once a workflow has been completed and the contract reaches the end of its process. | /workflows |
workflow_cancelled | Fires any time a workflow is cancelled. | /workflows/{id}/cancel |
workflow_paused | Fires when a workflow is paused. | /workflows/{id}/pause |
workflow_resumed | Fires when a paused workflow is resumed. | /workflows/{id}/resume |
workflow_approval_status_changed | Fires when an approver approves a workflow or an approval status otherwise changes. | /workflows/{id}/approvals/{roleId} |
contract_status_changed | Fires when a contract record's status changes, like moving from active to expired. | /records/{id}/records/{id}/actions |
Ironclad limits how fast an app can call, by a per-minute request rate set per account that differs by resource and by whether a call reads or writes.
Ironclad meters requests by a per-minute rate set per account, and the ceiling depends on the resource and on whether a call reads or writes. Reads of workflows allow up to 400 requests per minute while writes to workflows allow 40; reads of records allow 600 while writes allow 200; webhook methods allow 600; and all other methods default to 800. SCIM user and group methods carry their own lower write limits. Going over returns HTTP 429 Too Many Requests, and the documented guidance is to retry on a 429 with exponential backoff.
List methods page through results rather than returning everything at once. A list call returns a page of results plus a cursor or page marker to fetch the next page, so an integration walks the full set by following the marker until no more pages remain.
Limits are expressed as a per-minute request rate per account rather than a fixed page-size cap, and the documentation does not publish a single maximum page size that applies across every list method.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | No valid token was provided, or the token has expired. | Send a valid Bearer token in the Authorization header, and refresh or reissue the OAuth token if it has expired. |
| 403 | Forbidden | The token is valid but lacks the OAuth scope the method requires, or the acting user is not permitted to perform the action. | Grant the method's named scope to the token, or act as a user who has the necessary permission in Ironclad. |
| 404 | Not Found | The requested workflow, record, document, or webhook does not exist, or is not visible to this token and acting user. | Verify the identifier and confirm the acting user can see the object in this Ironclad account. |
| 429 | Too Many Requests | The account exceeded the per-minute rate limit for this kind of call. | Back off and retry on an exponential backoff schedule, and smooth the request rate so it stays under the per-resource limit. |
Ironclad serves a single dated version of its public API under the v1 path and ships changes through release notes rather than minting new version strings, and it moved authentication to OAuth 2.0, deprecating the older static token.
Ironclad serves a single dated version of its public API under the v1 path, covering workflows, records, documents, webhooks, schemas, entities, and obligations. Additive changes ship through the developer release notes rather than as new version strings. Methods name the OAuth scope they require.
Ironclad moved API authentication to the OAuth 2.0 framework, with the authorization code grant and the client credentials grant. The previous static access token was deprecated, and existing legacy-token integrations keep working for now while OAuth 2.0 becomes the only supported method.
The public API is served under a single v1 path; track changes through the developer release notes.
Ironclad developer changelog ↗Bollard AI sits between a team's AI agents and Ironclad. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.