> ## 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.

# Scoped broker tokens

> Issue expiring, revocable broker credentials for Hookfish resource subtrees.

The root `HOOKFISH_API_KEY` can access every Hookfish resource. Give applications
and workers named, expiring broker tokens instead of sharing that root key.

## Define resource paths

Connections, dynamic providers, and vault secrets share one slash-delimited
namespace:

```text theme={null}
acme/engineering/github
acme/engineering/notion
acme/finance/github
```

A submitted scope of `acme/engineering` is canonicalized to
`acme/engineering/**`. It includes the exact path and descendants, but not
`acme/engineering-tools`. Use `**` only for root access.

Paths can be at most 512 characters. They must use canonical NFC Unicode and
cannot contain empty segments, dot segments, backslashes, control characters,
or encoded path structure.

## Mint a token

Use a root credential to create a named one-hour token:

```bash theme={null}
curl --request POST http://127.0.0.1:8787/api/admin/tokens \
  --header "Authorization: Bearer $HOOKFISH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "acme-worker",
    "scopes": ["acme/engineering"],
    "expires_in": 3600
  }'
```

```json theme={null}
{
  "name": "acme-worker",
  "access_token": "hookfish_at_v1.eyJ2IjoxLC...",
  "token_type": "Bearer",
  "scopes": ["acme/engineering/**"],
  "expires_at": "2026-08-11T20:00:00.000Z"
}
```

The bearer value is returned once. Store it in the consuming service's secret
manager.

## Use and delegate the token

Send a scoped token through the same header used by the root key:

```bash theme={null}
curl http://127.0.0.1:8787/api/oauth/connections/acme/engineering/github \
  --header "Authorization: Bearer $HOOKFISH_ACCESS_TOKEN"
```

Requests outside every granted scope return `403 insufficient_scope`.

A scoped token may create another token with the same or narrower scopes and an
equal or earlier expiry. Names form a delegation namespace: `acme-worker` may
mint `acme-worker.eu`, but not `production-api`.

| Limit                   | Value      |
| ----------------------- | ---------- |
| Default lifetime        | 1 hour     |
| Minimum lifetime        | 60 seconds |
| Maximum lifetime        | 30 days    |
| Maximum resource scopes | 32         |

## Revoke access

```bash theme={null}
curl --request DELETE http://127.0.0.1:8787/api/admin/tokens/acme-worker \
  --header "Authorization: Bearer $HOOKFISH_API_KEY"
```

Hookfish stores a hash of each token's random identifier and checks the
database record on every request. Deletion, expiry changes, and scope narrowing
take effect on the next request.

<Warning>
  Rotating `HOOKFISH_API_KEY` invalidates every scoped token because the root key
  signs them. Treat root-key rotation as a deployment-wide credential rollover.
</Warning>