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:
- Main Resource Layer: This layer represents the main resource that the corresponding APIs can access.
- Action Category Layer: This layer categorizes all corresponding APIs. For example,
download
scope relates to the downloading behavior of a resource, whilemanagement
scope relates to the workflow management of that resource. Thegeneral
scope encompasses basic actions, which is the default scope that cannot be deselected once you have selected the resource from the first layer. - Read/Write Operation Layer: This layer distinguishes between
read
andwrite
operations. Theread
scope is limited to retrieving resources, typically used withGET
HTTP methods. In contrast, thewrite
scope indicates actions where some data will be created or modified, commonly associated withPOST
,PUT
, andDELETE
HTTP methods."
Scope | Description |
---|---|
embedded_signing | Used to initiate embedded signing, can obtain a token through the Client Credentials Flow. |
files.general.read | Read operations on file missions, such as getting a file mission information. |
files.general.write | Write operations on file missions, such as creating a file mission to merge multiple files to create a task. |
groups.general.read | Read operations on group's data, such as name, email display name and icon. |
groups.general.write | Write operations on group's data, such as name, email display name and icon. |
groups.seals.read | Read operations on group seals, such as retrieving seals list. |
groups.seals.write | Write operations on group seals, such as creating a seal. |
groups.sign_tasks.read | Read operations on group related tasks, such as retrieving task lists that are created by group members. |
members.general.read | Read operations on member's data, such as email, preferences and plan. |
members.general.write | Write operations on member's data, such as name, lang and icon. |
members.signatures.read | Read operations on member's signatures, such as retrieving signatures list. |
members.signatures.write | Write operations on member's signatures, such as creating a signature, deleting a signature. |
public_forms.download.read | Download operations on public forms, such as downloading the CSV file of a form. |
public_forms.general.read | General read operations on public forms, such as retrieving form lists. |
public_forms.general.write | General write operations on public forms, such as creating or updating a form. |
public_forms.management.write | Management operations on public forms, such as deleting a form. |
sign_tasks.download.read | Download operations on tasks, facilitating access to task documents, such as audit trail or attachments. |
sign_tasks.general.read | General read operations on tasks, such as retrieving task lists or specific task details. |
sign_tasks.general.write | General write operations on tasks, such as creating or updating tasks. |
sign_tasks.management.read | Read operations on task management, such as list archived tasks. |
sign_tasks.management.write | Write operations on task management, such as voiding the task. |
sign_tasks.signing.write | Signing operations on tasks, such as changing signer of a task. |
templates.general.read | General read operations on templates, such as retrieving template lists or specific template details. |
templates.general.write | General write operations on templates, such as creating or updating templates. |
templates.management.write | Management 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 thesign_tasks.general.write
scope.
By understanding and appropriately utilizing the available scopes, you can ensure secure and efficient integration with DottedSign API.
Updated 5 days ago