> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/authorization-and-resource-scope.md).

# Authorization and Resource Scope

Authentication identifies the caller. Authorization checks whether that caller can perform an operation on the requested resource.

![Check permission for each operation](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FvXXyZXF7sPwN87MyZBi1%2Fauthorization-and-resource-scope.png?alt=media)

Scopes apply per operation. The caller must also have access to the organization and target resource; a valid credential alone is not enough.

<details>

<summary>Copy the example</summary>

```http
# Inspect the project's input contract
GET /v2/projects/{project_id}/io-schema
# Required scope: projects.read

# Start a run
POST /v2/runs
# Required scope: projects.run

# Read the run's status and result
GET /v2/runs/{run_id}
# Required scope: analytics.read
```

</details>

## Before you begin

A valid credential, its required scopes, and access to the target organization and resource.

## Key concepts

| Term           | Definition                                                                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authentication | Verification of the account or credential making a request. It identifies the caller but does not grant every resource permission.                                       |
| Authorization  | The decision whether a caller can perform an operation on a resource. Check roles, scopes, organization context, and sharing when access is denied.                      |
| Scope          | A permission category requested by an application or assigned to a key. A scope permits an operation class; resource-level restrictions can still apply.                 |
| Organization   | The team-level container for members, roles, projects, connections, and settings. Select the correct organization before looking for a resource or calling an operation. |
| Resource ID    | A stable identifier for a project, file, connection, or other resource. Use the required ID type; matching display names do not make IDs interchangeable.                |

## Check API access

1. Select the intended organization context.
2. Use the correct resource ID and a credential authorized for the operation.
3. Handle an access failure by checking scopes, membership, and resource sharing.

The caller can perform the operation within its permitted scope.

## Behavior and limitations

A valid key does not grant access to every project. Starting a run and reading analytics can require different permissions. Resource identifiers are not credentials. Do not broaden key scopes to compensate for an incorrect organization or resource ID.

## Related resources

[API Versions and Compatibility](https://docs.stackai.com/technical-reference/apis-and-mcp/api-versions-and-compatibility.md)


---

# 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.stackai.com/technical-reference/apis-and-mcp/authorization-and-resource-scope.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.
