Scopes define what an application can access or modify through the API. They provide fine-grained permission control based on the integration’s needs.
All applications—regardless of which scopes they request—have access to basic information about users, clients, and projects. Any additional permissions come only from explicitly granted scopes.
The most powerful scope is:
integrationWhen an application includes the integration scope:
- The application acts as a dedicated system user
- All permissions are defined solely by the granted scopes
- It does not automatically receive full permissions
- Other scopes explicitly determine what the integration is allowed to do
This mode is recommended for:
- Standalone integrations
- Server-to-server applications
- Automated systems
Direct Access Tokens behave like dedicated system users. (Integration Scope) However:
The actual permissions still depend entirely on the scopes attached to the token.
If an application does not include the integration scope:
- The app acts as the authenticated human user
- It inherits the user’s permissions, including their role and team restrictions
- Additional scopes expand the app’s capabilities beyond the user’s base permissions
This mode is suitable for:
- OAuth applications acting on behalf of a user
- Tools that should respect user-level privacy and visibility settings
| Scope | Description |
|---|---|
integration | Acts as a system user; all permissions are explicitly defined by scopes |
| Scope | Description |
|---|---|
user:read | Read full information about users |
| Scope | Description |
|---|---|
client:read | Read full client information |
client:write | Create, update & delete clients |
| Scope | Description |
|---|---|
contact-data:read | Read contact & companies |
contact-data:write | Create, update & delete projects |
| Scope | Description |
|---|---|
task-management:read | Read tasks, comments, phases, milestones, and epics |
| Scope | Description |
|---|---|
efforts:read | Read project efforts |
efforts:extended:read | Read admin & project efforts |
| Scope | Description |
|---|---|
user_group:read | Read user groups |
| Scope | Description |
|---|---|
offer:read | Read offers |
| Scope | Description |
|---|---|
outgoing-invoice:read | Read invoices & plans |
outgoing-invoice:upload | Upload & create external outgoing invoices |
| Scope | Description |
|---|---|
payments:read | Read payment accounts & payments |
payments:write | Create & update payment accounts & payments |
All apps have access to basic information about users, clients, and projects.
With
integrationscope:- The app acts as a system user
- Permissions are determined only by the scopes attached
Without
integrationscope:- The app acts as the authenticated user
- Permissions = User permissions + granted scopes