GuidesAPI ReferenceRecipes
Request a Demo

Guidance for Migrating to OAuth Tokens

Migrating from Legacy Tokens to OAuth Tokens

When migrating an integration from using legacy tokens to OAuth tokens, key changes to consider include user scoping and resource scoping of the token.

User Scoping:

Legacy tokens are scoped as company admins and aren’t tied to individual users. OAuth tokens, however, involve a user’s authorization to access their resources, tying them to the consenting user and inheriting the user’s permissions. For example, a company admin can view all workflows, while an individual might only access a subset of workflows based on their group permissions. OAuth tokens enable user permissioning, aligning with system permissions and improving security without requiring separate permissioning infrastructure in applications.

Resource Scoping:

OAuth tokens enforce resource scoping, ensuring issued tokens have only the necessary permissions. Resource scopes dictate the endpoints accessible by a token. For instance, the scope public.workflows.readWorkflows allows access to the GET /public/v1/workflows endpoint. Legacy tokens lack resource scopes, making migration to OAuth require special consideration.

API Endpoint Changes:

  • GET /workflow-schemas?form=launch

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

  • GET /workflows

    • Legacy Token: Returns all workflows at the company (paginated).
    • OAuth Token: Returns workflows the token user can view (paginated).

  • GET /workflows/:workflowId

    • Legacy Token: Workflow can always be retrieved.
    • OAuth Token: Workflow can be retrieved if the token user can view it.

  • POST /workflows

    • Legacy Token: Launch and creator permissions tied to the “creator” object.
    • OAuth Token: Launch and creator permissions tied to the user associated with the token.

  • POST /workflows/async

    • Same as POST /workflows.

  • GET /workflows/async/:jobId

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

  • GET /workflows/:workflowId/signatures

    • Legacy Token: Access to all workflows and their signatures.
    • OAuth Token: Signatures returned only if the token user has access to view the workflow.

  • GET /workflows/:workflowId/approvals

    • Legacy Token: Access to all workflows and their approvals.
    • OAuth Token: Approvals returned only if the token user has access to view the workflow.

  • GET /workflows/:workflowId/approval-requests

    • Legacy Token: Access to all workflows and their approval requests.
    • OAuth Token: Approval requests returned only if the token user has access to view the workflow.

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

    • Legacy Token: All workflows documents can be downloaded.
    • OAuth Token: Documents can be downloaded only if the token user has access to view the workflow.

  • GET /records

    • Legacy Token: Returns all records at the company (paginated).
    • OAuth Token: Returns records the token user can view (paginated).

  • GET /records/:id

    • Legacy Token: Record can always be retrieved.
    • OAuth Token: Record can be retrieved if the token user can view it.

For more reading, please consult the Oauth 2.0 Authorization documentation and update your integration accordingly for a seamless migration from legacy tokens to OAuth tokens.