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:
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:
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:
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.
Revoke access
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.
Rotating HOOKFISH_API_KEY invalidates every scoped token because the root key
signs them. Treat root-key rotation as a deployment-wide credential rollover.