> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookfish.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource scopes and provider scopes

> Separate Hookfish resource authorization from upstream OAuth permissions.

Hookfish uses the word “scope” in two security systems. Apply both systems, but
do not treat them as interchangeable.

## Resource scopes

A Hookfish **resource scope** controls which connection IDs, dynamic providers,
and vault paths a broker access token may use.

```text theme={null}
acme/**
acme/payments/**
acme/support/**
```

Resource paths are slash-delimited identifiers owned by Hookfish. A scope of
`acme/payments/**` covers the exact `acme/payments` path and its descendants. It
does not cover `acme/payment-tools` or another path where the same text appears
later.

Use resource scopes to give a service access to one subtree without sharing the
root `HOOKFISH_API_KEY`. See [Token scoping](/authorization/token-scoping) for
minting, delegation, expiry, and revocation.

## Provider scopes

An OAuth **provider scope** controls what an upstream provider token can do.
Pass provider scopes when you start authorization:

```json theme={null}
{
  "connection_id": "acme/engineering/github",
  "scopes": ["read:user", "repo"]
}
```

The provider defines these values. Hookfish passes them through the provider
implementation and records the granted scopes with the connection.

## Apply both layers

Suppose a worker has a broker token scoped to `acme/engineering/**`. It can
retrieve the provider token stored at `acme/engineering/github`, but it cannot
read `acme/finance/github`.

The retrieved GitHub token can perform only the operations allowed by the
GitHub scopes approved during consent.

| Question                                                      | Controlled by                             |
| ------------------------------------------------------------- | ----------------------------------------- |
| Which Hookfish paths can this service access?                 | Resource scopes                           |
| Which GitHub or Notion operations can the connection perform? | Provider scopes                           |
| Which tenant is active for this request?                      | Organization routing and your application |

<Note>
  A narrow resource scope does not compensate for broad provider permissions.
  Narrow provider permissions do not prevent access to sibling Hookfish
  connections.
</Note>