# Scopes & Permission Model

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.

## 1. Integration Scope

The most powerful scope is:


```
integration
```

When 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

Direct Access Tokens behave like dedicated system users. (Integration Scope)
However:

> **The actual permissions still depend entirely on the scopes attached to the token.**


## 2. Without Integration Scope

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


## 3. Available Scopes

### General

| Scope | Description |
|  --- | --- |
| `integration` | Acts as a system user; **all permissions are explicitly defined by scopes** |


### Users

| Scope | Description |
|  --- | --- |
| `user:read` | Read full information about users |


### Clients

| Scope | Description |
|  --- | --- |
| `client:read` | Read full client information |
| `client:write` | Create, update & delete clients |


### Contacts & Companies

| Scope | Description |
|  --- | --- |
| `contact-data:read` | Read contact & companies |
| `contact-data:write` | Create, update & delete projects |


### Task Management

| Scope | Description |
|  --- | --- |
| `task-management:read` | Read tasks, comments, phases, milestones, and epics |


### Efforts

| Scope | Description |
|  --- | --- |
| `efforts:read` | Read project efforts |
| `efforts:extended:read` | Read admin & project efforts |


### User Groups

| Scope | Description |
|  --- | --- |
| `user_group:read` | Read user groups |


### Offers

| Scope | Description |
|  --- | --- |
| `offer:read` | Read offers |


### Outgoing Invoices/Credits

| Scope | Description |
|  --- | --- |
| `outgoing-invoice:read` | Read invoices & plans |
| `outgoing-invoice:upload` | Upload & create external outgoing invoices |


### Payments

| Scope | Description |
|  --- | --- |
| `payments:read` | Read payment accounts & payments |
| `payments:write` | Create & update payment accounts & payments |


## 4. Summary

* **All apps** have access to basic information about users, clients, and projects.
* **With `integration` scope:**
  * The app acts as a system user
  * **Permissions are determined only by the scopes attached**
* **Without `integration` scope:**
  * The app acts as the authenticated user
  * **Permissions = User permissions + granted scopes**