API Scopes
Scopes are used to grant limited access to user data and Hub functionality. When an application requests an access token, it specifies a list of scopes. The user must approve these scopes during the 3-legged authorization flow.
Available Scopes
| Scope | Description | Level |
|---|---|---|
data:read | View your conversations, messages, and files. | User |
data:write | Send messages and update existing data. | User |
workflow:execute | Trigger and run automated workflows. | Account |
workflow:read | View workflow definitions and execution logs. | Account |
connection:manage | Create, update, and delete tool connections. | Account |
user:profile | Access basic profile info (email, name). | User |
admin:access | Full administrative access to the organization. | Org |
Best Practices
- Least Privilege: Only request the scopes necessary for your application to function.
- Incremental Scopes: If your application gains new features, you can prompt the user to re-authorize with additional scopes later.
- Internal vs. External: Some scopes (like
admin:access) are restricted and may require manual approval by Arrotech for third-party apps.
Token Expiration
Access tokens generated with specific scopes typically expire in 1 hour. Refresh tokens can be used to obtain new access tokens without re-prompting the user, provided the user has not revoked the application's access.