---
schema: formation.doc/v0.1
kind: doc
visibility: public
canonical_url: https://topologyindex.com/docs/api/authentication.md
credential_prefix: fmk_
path: /docs/api/authentication.md
product_api_version: v1
schema_version: v0.1
scheme: bearer
scopes:
  - artifacts:read
  - formations:write
  - recommendations:read
  - evaluations:plan
  - evaluations:start
  - evaluations:read
  - evaluations:cancel
  - runs:report
  - adoptions:write
  - subscriptions:write
  - events:read
  - account:read
title: Authentication
---

# Authentication

Private routes take `Authorization: Bearer fmk_<credential_id>_<secret>`. The credential is
opaque and high entropy; only a keyed hash of the secret is stored, and verification is
constant time. Credentials are provisioned by the operator and rotated or revoked without a
website. Never place a credential in a URL, a document or a chat transcript.

## Rules

- The tenant is the credential's tenant. A different tenant in the path is an unknown resource (404).
- A missing or invalid credential is 401 `invalid_credentials`.
- A valid credential without the operation's scope is 403 `insufficient_scope`.
- Runner routes need a credential bound to a runner principal with `runs:report`.
- Revocation takes effect on the next request; already leased work follows its lease policy.