The following details some considerations for how to structure integrations that query the Ironclad API.
Access Token Entity Scope
Ironclad access tokens generated via different methods have different entity scope and this is an important factor in determining how to structure your integration.
The authorization code grant will always generate a token associated with the consenting user within a company context and a client application. As a result, requests made with that token will have the same access as that user within the company and permissions and data filtering will be applied accordingly.
The client credentials grant on the hand will always generate a token associated with a company and a client application. However, resource requests made with these tokens must include either the x-as-user-id or x-as-user-email header to denote which user the request is being made on behalf of. In practice, this means that within the context of a request, the accessing entity will be considered a specific user in a company similar to a token generated from the authorization code grant, and permissions and data filtering will be applied accordingly.
For example: When queried with an OAuth-generated token, the List All Workflows endpoint will return workflows that the associated user has permission to see in the associated company. Endpoints like the Create a Workflow endpoint or the Update Approval endpoint will act on behalf of the user associated with the token or user impersonation header, launching workflows with that user as the creator and approving workflows on behalf of that user respectively. Any creator or approver parameters included in some endpoint request bodies are deprectaed and will be ignored in favor of the user associated with the token or user impersonation header.
Certain endpoints, like the List All Webhooks endpoint will only be accessible by access tokens associated with users who would have permission to access those resources in the UI (e.g. users with the API configuration permission, generally admininstrators). So a token generated from an OAuth grant with a standard non-admin user would not be able to create, update, read, or delete webhooks.
Legacy Access Tokens
The entity scope of access tokens generated via an OAuth client application differs from that of legacy access tokens. These deprecated legacy access tokens have company scope and act effectively as fully permissioned company administrators with full access to all endpoints and data.
Integration Authorization Design Patterns
Integrations and scripts that query the Ironclad API will need to be designed with the user-in-company-scoped access token in mind. There are generally three different designs that would work for authenticating your integration.
Admin-Like or Service Account Connection
In this design, you would have a user or service account with admin-like permissions to all necessary resources in Ironclad. With the authorization code grant, you would have that user go through the authorization flow to generate a user-in-company-scoped token that has those admin-like permissions associated. With the client credentials grant, you would send requests with a x-as-user-id or x-as-user-email header with that user's identifier or email.
Subsequent requests will be able to access all resources available to the admin user (e.g. all workflows returned by the List All Webhooks endpoint) and access all endpoints authorized by the resource scopes (e.g. be able to create webhooks via the Create a Webhook endpoint). Note however that requests made with this token will have the associated user as a creator/approver/etc and permissions will be limited to that user (e.g. this token cannot approve on behalf of other users).
This design would be useful when you have a company-level integration that doesn’t need to take actions or scope resource requests by the user, and so you can simplify the setup process by just having an admin-like user or service account user do the connection.
User Connections
In this design, you would have many individual users who are going to be accessing the integration. With the authorization code grant, each Ironclad user would go through the authorization flow, generating many user-in-company-scoped tokens specific to each user. With the client credentials grant, different requests to the Ironclad API would include a different x-as-user-id or x-as-user-email header to denote who each request is being made on behalf of.
Subsequent requests will be able to access all non-admin endpoints accessible via the resource scopes and the results and permissions for the requests will be scoped to each individual user’s permissions in Ironclad (e.g. the List All Webhooks endpoint will return the workflows that the user connected to the token or specified in the user header has access to see and the Update Approval endpoint will only allow a token or request associated with the approval’s user, make the approval).
This design would be most useful when you want the integration to show users the resources that they have access to and allow users to take actions like creating and approving workflows on behalf of themselves, but your integration does not need to access any admin-only endpoints.
Admin-Like or Service Account and User Connections
In this design, for the authorization code grant, you would have an Ironclad admin or service account with admin-like permissions go through the authorization flow once and then have individual users go through the authorization flow as well. For the client credentials grant, you would send requests that needed higher level admin-like permissions with the Ironclad admin or service account in the user header and requests that needed to represent individual user permissions with the individual user in the user header.
This is the recommended design when you want your integration to both respect user-in-company-scoping and permissioning while also being able to access admin-only endpoints like webhooks.