Procedure 02 / Authentication
Bearer capability.
A token is a scoped capability bound to one instance. It is not an OAuth identity, a session cookie, or a password. The server verifies it without a session lookup.
The header
Every route except /health requires a bearer credential.
Authorization: Bearer gnm1.<claims>.<signature>A missing, malformed, expired, revoked, or wrong-instance token is denied. The scheme name is case-insensitive; the token is not.
One protected call
curl -sS "$GNOMON_API_URL/status" -H "Authorization: Bearer $GNOMON_TOKEN"Tiers
| Tier | Reaches | Not implied |
|---|---|---|
DEVELOPER | /status, /instance, /account, engine routes | Roster and security administration |
OPERATOR | /accounts, account lifecycle, security certificates | Engine routes |
The tier rule is horizontal. An operator token is not a developer token and does not implicitly reach observation, query, emission, or derivation. Developer access is issued as a DEVELOPER account.
Failure status
| Status | Error | Meaning |
|---|---|---|
| 401 | malformed | The token envelope or claims did not parse. |
| 401 | bad_signature | The signature does not verify against the instance and epoch. |
| 401 | wrong_instance | The token was issued by another instance. |
| 401 | unknown_account | The account is not in this roster. |
| 401 | account_inactive | The account is suspended or revoked. |
| 401 | stale_epoch | The token predates the account's minimum epoch. |
| 401 | expired | The token is outside its issuance window. |
| 403 | tier_mismatch | The token's tier is below the route's requirement. |
| 403 | capability_denied | The token's capability list excludes this route. |
Capabilities
A token may carry an optional capability list. When the list is non-empty, the requested route must appear in it. An empty list does not add restrictions beyond the tier. Treat capabilities as a narrowing mechanism, not as a replacement for a separate account.
Lifecycle
- Tokens are issued by an operator. There is no self-serve issuance route.
- Expiry is bounded by instance heartbeats, not wall-clock time.
- An idle or stopped instance freezes the auth clock; expiry does not advance while it is down.
- Rotation and revocation are account-wide. There is no per-token kill switch.
- Revocation raises the account's minimum epoch; older tokens stop verifying.
- Tokens are bound to the instance origin. A token from another instance does not transfer.
Instance model
An instance is single-tenant. Accounts are access control over one shared substrate, not isolated memory partitions. Do not share one instance between unrelated projects.
Handling
- Treat the token as a password. Never place it in a URL, commit it, or log it.
- Use TLS. A bearer token has no channel binding; interception within its lifetime is enough to replay it.
- Rotate if exposure is suspected. Rotation invalidates the account's older tokens, not just the exposed one.
- Use a dedicated token per environment when tokens are provisioned that way.
Next: HTTP API for route contracts, or Errors & limits for retry behavior.