# Auth

> The Auth operations of the Hub REST API (2 operations).

URL: https://docs.synap.live/docs/reference/hub-api/auth · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /auth/status

Introspect the calling bearer credential

Returns metadata about the API key that authenticated this request — id, owning user, scopes, expiry, last-used-at. Used by Eve CLI and external operators to verify their credential without making privileged calls. Returns 401 if no valid bearer was supplied.

Responses:

- `200`: Bearer credential introspection.
- `400`: Bad request — the wrapped door refused the input
- `401`: Auth failed. See `reason` field for the specific cause.
- `403`: Forbidden — bearer is not an API key (e.g. session-token caller)
- `404`: Key was accepted by the auth middleware but its row was deleted concurrently.
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## GET /auth/key-state

Why the presented key does or does not work (holder only)

Answers the HOLDER of the bearer key — valid or not — with its state: `active`, `awaiting_approval` (+ the approval page), `revoked` (+ when, why, and when/where a replacing connection was created), `expired`, or `unknown` for a secret this pod never issued. Looked up by the secret only; reveals nothing about any key the caller does not hold.

Responses:

- `200`: The presented key's state.
- `401`: Auth failed. See `reason` field for the specific cause.
- `403`: A guest's key: refused, never described.
- `500`: Internal error