API Scopes

API Scopes define the restrictions your application is permitted to adhere to when using the DottedSign API. Selecting the appropriate scopes ensures your application has the necessary permissions to perform its intended actions while avoiding unnecessary access to sensitive data.

Available Scopes

Each scope is comprised of three layers:

  1. Main Resource Layer: This layer represents the main resource that the corresponding APIs can access.
  2. Action Category Layer: This layer categorizes all corresponding APIs. For example, download scope relates to the downloading behavior of a resource, while management scope relates to the workflow management of that resource. The general scope encompasses basic actions, which is the default scope that cannot be deselected once you have selected the resource from the first layer.
  3. Read/Write Operation Layer: This layer distinguishes between read and write operations. The read scope is limited to retrieving resources, typically used with GET HTTP methods. In contrast, the write scope indicates actions where some data will be created or modified, commonly associated with POST, PUT, and DELETE HTTP methods."
ScopeDescription
embedded_signingUsed to initiate embedded signing, can obtain a token through the Client Credentials Flow.
files.general.readRead operations on file missions, such as getting a file mission information.
files.general.writeWrite operations on file missions, such as creating a file mission to merge multiple files to create a task.
groups.general.readRead operations on group's data, such as name, email display name and icon.
groups.general.writeWrite operations on group's data, such as name, email display name and icon.
groups.seals.readRead operations on group seals, such as retrieving seals list.
groups.seals.writeWrite operations on group seals, such as creating a seal.
groups.sign_tasks.readRead operations on group related tasks, such as retrieving task lists that are created by group members.
members.general.readRead operations on member's data, such as email, preferences and plan.
members.general.writeWrite operations on member's data, such as name, lang and icon.
members.signatures.readRead operations on member's signatures, such as retrieving signatures list.
members.signatures.writeWrite operations on member's signatures, such as creating a signature, deleting a signature.
public_forms.download.readDownload operations on public forms, such as downloading the CSV file of a form.
public_forms.general.readGeneral read operations on public forms, such as retrieving form lists.
public_forms.general.writeGeneral write operations on public forms, such as creating or updating a form.
public_forms.management.writeManagement operations on public forms, such as deleting a form.
sign_tasks.download.readDownload operations on tasks, facilitating access to task documents, such as audit trail or attachments.
sign_tasks.general.readGeneral read operations on tasks, such as retrieving task lists or specific task details.
sign_tasks.general.writeGeneral write operations on tasks, such as creating or updating tasks.
sign_tasks.management.readRead operations on task management, such as list archived tasks.
sign_tasks.management.writeWrite operations on task management, such as voiding the task.
sign_tasks.signing.writeSigning operations on tasks, such as changing signer of a task.
templates.general.readGeneral read operations on templates, such as retrieving template lists or specific template details.
templates.general.writeGeneral write operations on templates, such as creating or updating templates.
templates.management.writeManagement operations on templates, such as deleting a template.

🚧

Choose the Right Scopes

It is important to select only the minimum scope required for your application's functionality, as this helps avoid unnecessary access and protects user data privacy.

For example, if your application only needs to display a list of completed tasks for the user, you should apply only the sign_tasks.general.read scope. However, if your application evolves to allow users to create new tasks, you would then apply the sign_tasks.general.write scope.

By understanding and appropriately utilizing the available scopes, you can ensure secure and efficient integration with DottedSign API.