Repository navigation
EN Authentication
English · Türkçe · Languages / Diller
Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English
| Credential | Where it is sent | Purpose |
|---|---|---|
| Project API key |
X-API-Key by default |
One application's HTTP API |
| Project bootstrap key | Same header during initial setup | Create the first persistent key |
| Application JWT | Authorization: Bearer … |
Explicitly enabled JWT identity |
| Operator token |
X-Forge-Operator-Token or operator Bearer |
Process metrics and detailed readiness |
| Editor setup token | Founder setup | One-time management account creation |
| Editor session | Control-plane Bearer | Team and document management |
A project administrator key is not an Editor account. An operator token does not grant project CRUD permissions. Use separate secrets for these trust boundaries.
bootstrap_enabled defaults to false. CLI starter projects explicitly enable it and reference an environment variable. With bootstrap_one_time: true, the first successful POST <prefix>/admin/api-keys consumes bootstrap in the same operation. Make sure the first persistent key can continue the required administration.
The creation body includes name, roles, permissions, tenant_id, expiry and rate budgets. The raw api_key appears once in the creation response. Later listing cannot reconstruct it from its stored hash.
Use the persistent administrator credential to provision narrowly scoped application keys. GET /admin/api-keys lists keys and DELETE /admin/api-keys/{key_id} revokes them, relative to the project prefix. Required permissions are admin.keys.create, admin.keys.list and admin.keys.revoke respectively.
Creating a child credential does not bypass the parent's roles, permissions, tenant, expiry, rate budget or subject boundaries. Unrestricted delegation/impersonation requires its explicit high-trust permissions. admin.keys.create alone does not mean unlimited administrator creation.
Enable security.jwt_enabled=true, choose jwt_provider="local_hs256" and provide a strong jwt_secret. A caller with admin.jwt.issue can request a token through /admin/jwt. Expiry and principal/claim checks apply. Revoking an API key should not be assumed to revoke every JWT previously issued through it; use short lifetimes and an explicit rotation policy.
For jwt_provider="jwks", configure the JWKS URL, issuer, audience, allowed asymmetric algorithms and subject/role/permission/tenant/project claim paths. jwt_require_project_claim defaults to true. Trust in role, permission and tenant claims is disabled by default; enable only claims reliably controlled by your identity provider.
A valid identity-provider token does not automatically confer Forge administrator permissions. Database connections and row policies remain separate layers.
The v0.5.1 JWKS client enforces HTTPS, response-size/time limits, asymmetric algorithm rules, private-network/DNS-rebinding protection and bounded caching. A changed kid can trigger cache refresh. Options such as jwks_allow_private_networks and jwks_allow_insecure_http alter the trust boundary; do not enable them merely to suppress a connection error.
API-key metadata cache TTL defaults to 2 seconds and can be disabled with 0. Creation/revocation invalidates the local worker immediately; other workers can retain their cached state until TTL expiry. Account for this if you need immediate revocation across workers.
Query-string API-key options default to disabled. Prefer headers because URLs can appear in history, referrers and proxy logs. See the security model reference.
This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.
main/framework/security.pymain/framework/api_models.pymain/framework/config.pymain/docs/35-Credential-Delegation-JWT-and-Operator-Trust.md