GuidesAPI ReferenceRecipes
API Reference
Request a Demo

Migrating to OAuth 2.0

When migrating an integration from using legacy access tokens to OAuth-based tokens, key changes to consider include etnity scoping and resource scoping of the token. More details can be found on the Authentication Design Considerations page.

Entity Scoping:

Legacy access tokens have company-wide access. You can think of their level of access as a fully permissioned company admin. These tokens are not tied to individual users. Tokens derived from the OAuth 2.0 Authorization Code grant however, involve an explicit user’s authorization to access their resources in Ironclad, tying the token to the consenting user and inheriting that user’s permissions. Tokens derived from the OAuth 2.0 Client Credentials grant, are not tied to individual users; however, requests made with these tokens must include an x-as-user-id or x-as-user-email header to denote who the request is being made on behalf of. In practice, this means that Ironclad API requests made with OAuth-based tokens have an entity scope of a "user within a company", meaning that whether that token can perform an action is dependent on the user's permissions in Ironclad. Additionally, the data that is returned by the request will be filtered to data that the user can see in Ironclad.

For example, a fully-permissioned admin can view all workflows, while an individual user might only be able to access a subset of workflows based on their group permissions. Thus, a legacy access token sending a request to the List All Workflows endpoint would receive all workflows back in the response while an OAuth-based token accessing the same endpoint would only receive the workflows back that the associated user has access to.

Similarly, a legacy access token sending a request to the Update Approval endpoint can make that approval on behalf of any user in the system, while an OAuth-based token sending that request can only approve if the associated user is assigned to that approval.

A huge advantage to this system is that instead of an integration having to try to replicate Ironclad permissions to ensure that users only have access to the data and actions they should have access to, you can leave it to the Ironclad API to determine the appropriate level of access. This shift requires special attention when migrating your integrations from legacy access tokens to OAuth-based tokens due to the difference in token access.

Resource Scoping:

In addition to the entity scope of API access tokens, OAuth-based tokens enforce resource scoping. Resource scopes limit what OAuth-based tokens can access, to what resource actions have been explicitly granted to the token during the OAuth exchange, ensuring that tokens have only the minimum necessary permissions they need for their functionality. This is a huge advantage over legacy access tokens, since it allows you to limit the access that an integration has to Ironclad data.

Ultimately, resource scopes dictate the endpoints accessible to a token. For instance, the scope public.records.readRecords allows access to the List All Records endpoint. So an integration with a token scoped with public.records.readRecords cannot, for example, delete records via the Delete a Record endpoint allowing you to more properly safeguard your data.

Since legacy access tokens don't have resource scopes, when you migrate your integration to using OAuth 2.0, you need to make sure that you request the proper resource scopes to perform the Ironclad API actions your integration needs access to.

Example API Endpoint Response Changes:

To inform any migration from legacy access tokens to OAuth-based tokens, here are some examples for the workflow-related endpoints to demonstrate the difference in behavior. Unlisted endpoints follow a similar behavioral pattern with entity scope dictating the level of access.

  • GET /workflow-schemas?form=launch

    • Legacy Access Token: All schemas returned.
    • OAuth-Based Token: Only schemas viewable or launchable by the associated user are returned. An additional “permissions” property denotes launch versus view permissions in the response.

  • GET /workflows

    • Legacy Access Token: Returns all workflows at the company (paginated).
    • OAuth-Based Token: Returns workflows the associated user can view at the company (paginated).

  • GET /workflows/:workflowId

    • Legacy Access Token: Workflow can always be retrieved.
    • OAuth-Based Token: Workflow can be retrieved if the associated user can view it.

  • POST /workflows / POST /workflows/async

    • Legacy Access Token: Launch and creator permissions tied to the “creator” object in the payload.
    • OAuth-Based Token: Launch and creator permissions tied to the associated user. If provided in the payload, the "creator" object will be ignored.

  • GET /workflows/async/:jobId

    • Legacy Access Token: Workflow launch status can always be retrieved.
    • OAuth-Based Token: Only the token that launched the workflow can retrieve its status.

  • GET /workflows/:workflowId/signatures / GET /workflows/:workflowId/approvals

    • Legacy Access Token: Access to all workflows and their signatures / approvals.
    • OAuth-Based Token: Signatures / approvals returned only if the associated user has access to view the workflow.

  • PATCH /workflows/:workflowId/approvals/:roleId

    • Legacy Access Token: Can approve on behalf of any user determined by the "user" object in the payload.
    • OAuth-Based Token: Can only approve if the approval is assigned to the associated user. If provided in the payload, the "user" object will be ignored.

  • GET /workflows/:workflowId/approval-requests / GET /workflows/:workflowId/turn-history

    • Legacy Access Token: Access to all workflows and their approval requests / turn histories.
    • OAuth-Based Token: Approval requests / turn histories returned only if the associated user has access to view the workflow.

  • POST /workflows/:workflowId/documents/:attributeId / POST /workflows/:workflowId/upload-signed

    • Legacy Access Token: Document upload permissions tied to the x-as-user-id or x-as-user-email header.
    • OAuth-Based Token: Document upload permissions tied to the associated user. If using a token from the Authorization Code grant, a user provided in the user header will be ignored.

  • GET /workflows/:id/document/:id/download

    • Legacy Access Token: All workflow documents can be downloaded.
    • OAuth-Based Token: Documents can be downloaded only if the associated user has access to view the workflow.

  • GET /workflows/:workflowId/participants

    • Legacy Access Token: Access to all workflows and their participants.
    • OAuth-Based Token: Participants returned only if the associated user has access to view the workflow.

  • PATCH /workflows/:workflowId/revert-to-review

    • Legacy Access Token: Can revert on behalf of any user determined by the "user" object in the payload.
    • OAuth-Based Token: Can only revert if the associated user has permissions to do so. If provided in the payload, the "user" object will be ignored.

  • POST /workflows/:workflowId/cancel / POST /workflows/:workflowId/pause / POST /workflows/:workflowId/resume

    • Legacy Access Token: Cancel/Pause/Resume permissions tied to the x-as-user-id or x-as-user-email header.
    • OAuth-Based Token: Cancel/Pause/Resume permissions tied to the associated user. If using a token from the Authorization Code grant, a user provided in the user header will be ignored.

  • POST /workflows/:workflowId/comments

    • Legacy Access Token: Can comment on behalf of any user determined by the “creator” object in the payload.
    • OAuth-Based Token: Can only comment if the associated user is a participant of the workflow. If provided in the payload, the "creator" object will be ignored.

  • GET /workflows/:workflowId/comments / GET /workflows/:workflowId/emails

    • Legacy Access Token: Access to all comments / emails on any workflow.
    • OAuth-Based Token: Comments / Emails returned only if the associated user has access to view the workflow.

  • PATCH /workflows/:workflowId/attributes

    • Legacy Access Token: Workflow attribute editing permissions tied to the x-as-user-id or x-as-user-email header.
    • OAuth-Based Token: Workflow attribute editing permissions tied to the associated user. If using a token from the Authorization Code grant, a user provided in the user header will be ignored.