> For the complete documentation index, see [llms.txt](https://docs.feathery.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.feathery.io/develop/api-authentication/scopes.md).

# Scopes

The access areas and scope names for OAuth apps and personal access tokens.

OAuth apps and personal access tokens only reach the areas you choose. In the **Developer** tab you pick a level for each area: No access, Read, Run, or Write. When you request an access token yourself, you name scopes instead, like `forms:read`.

| Area            | Scopes                                                     | Covers                                   |
| --------------- | ---------------------------------------------------------- | ---------------------------------------- |
| Forms           | `forms:read`, `forms:write`                                | Forms, fields, and form settings         |
| Submissions     | `submissions:read`, `submissions:write`                    | Users and their submission data          |
| Documents       | `documents:read`, `documents:write`                        | Document templates, fills, and envelopes |
| Extractions     | `extractions:read`, `extractions:write`, `extractions:run` | AI document extractions and their runs   |
| Data hubs       | `data_hubs:read`, `data_hubs:write`                        | Data hubs and their entries              |
| Computer agents | `computer_agents:read`, `computer_agents:run`              | Computer agents and their runs           |
| Logs            | `logs:read`                                                | Email, webhook, and integration logs     |
| Team            | `team:read`, `team:write`                                  | Members of your organization             |
| Workspaces      | `workspaces:read`, `workspaces:write`                      | Child workspaces                         |
| Audit logs      | `audit_logs:read`                                          | Your organization's audit log            |

### Levels for Each Area

| Area            | Levels           |
| --------------- | ---------------- |
| Forms           | Read, Write      |
| Submissions     | Read, Write      |
| Documents       | Read, Write      |
| Extractions     | Read, Run, Write |
| Data hubs       | Read, Write      |
| Computer agents | Read, Run        |
| Logs            | Read             |
| Team            | Read, Write      |
| Workspaces      | Read, Write      |
| Audit logs      | Read             |

### How Levels Map to Scopes

Each level includes the ones before it, and each scope includes the ones below it.

* **Read** gives the area's `read` scope.
* **Run** gives the area's `run` scope, which covers reading.
* **Write** gives the area's `write` scope, which covers reading and, for extractions, running.

Reading (`GET`) needs the `read` scope and other methods need `write`, or `run` for computer agents. A few endpoints need a different scope:

* Starting an extraction run needs `extractions:run`.
* Exporting a submission as a PDF needs `submissions:read`.
* Filling a document from a user's saved answers also needs `submissions:read`.

### What Each Role Can Choose

Personal access tokens can never do more than their owner's role allows:

| Role   | Can choose                                          |
| ------ | --------------------------------------------------- |
| Viewer | Read, outside Team, Workspaces, and Audit logs      |
| Editor | Any level, outside Team, Workspaces, and Audit logs |
| Admin  | Any level in any area                               |

OAuth apps are created by Admins and can have any access.

### Plan and Feature Requirements

* The developer API needs a paid plan.
* Computer agents need computer agents turned on for your organization.
* Audit logs need audit logs turned on for your organization.
* Workspaces need the Business plan with workspaces turned on.

### When Access Is Missing

A request outside the credential's access gets a `403` response. Its `WWW-Authenticate` header has `error="insufficient_scope"` and names the scope the request needs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.feathery.io/develop/api-authentication/scopes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
