Authentication and authority
How instance credentials, namespaces, actions, service policy, and operator controls fit together.
Hosted instance requests
Hosted dedicated mode requires signed capability verification. Send the issued credential in x-akasha-capability. The daemon verifies an Ed25519 JWT with typ: JWT, an EdDSA algorithm, the configured issuer and audience, and required expiry and identity claims. It then derives a namespace-scoped database and request authority from the verified payload.
GET /v1/keyspaces HTTP/1.1
Host: your-instance-host
x-akasha-capability: <issued-signed-capability>The token supplies namespace identity, actor, actions, and optional permitted keyspaces. A request body does not replace those grants. Missing or invalid credentials return 401; a verified request without the required authority returns 403.
The instance operator configures verification with AKASHA_REQUIRE_CAPABILITY, AKASHA_CAPABILITY_PUBLIC_KEY or AKASHA_CAPABILITY_PUBLIC_KEY_PATH, AKASHA_CAPABILITY_ISSUER, and AKASHA_CAPABILITY_AUDIENCE. These are server configuration, not fields for ordinary API requests. Hosted dedicated mode refuses startup when required verification is disabled.
Optional legacy JWT verification
When the daemon has a legacy JWT verifier configured, it also requires Authorization: Bearer <jwt>. Its algorithm and key family are pinned at startup. If capability verification is required at the same time, the signed capability header is still required. A bearer token is therefore not a universal substitute for the capability header.
Self-hosted deployments can configure a different authentication mode. Explicit local development compatibility for unsigned payloads exists in source; it is not the hosted credential contract. Do not build a production integration around unsigned JSON capability payloads.
Namespace and action permissions
| Route family | Authority domain | Typical action mapping |
|---|---|---|
| Episodic memory | memory:episodic | Insert: write. Search: query. Item GET/PUT/DELETE: read/update/delete. |
| Procedures | memory:procedural | Store: write. List/get: read. Search: query. Update/delete: matching action. |
| Resources | memory:resource | Store: write. Access record: update. Chunks: query. Remaining reads: read. |
| Vault | memory:vault | Store: write. Update/delete/search: matching action. Access log: admin. Other reads: read. |
| Cognitive memory | memory:cognitive | Query and usage: query. Singular resource lookup: read. Other operations: write. |
| Memory health, stats, and reindex status | memory:system | read |
| Working slots | memory:working | List/stats: read. Inject: write. Clear: delete. |
| MHN and SNN | memory:mhn, memory:snn | Handlers additionally enforce scoped action claims such as mhn:read, snn:execute, or snn:train. |
| Generic keyspace operations | Requested keyspace | Handler checks use the path or body’s actual keyspace. |
This table summarizes the centralized map. Each operation includes its direct handler checks. It is not a claim that every registered route uses the same authorization path.
The working-memory and cognitive configuration handlers call require_operator_control. Verified customer capabilities do not satisfy that check, including tokens carrying an admin action. Those daemon-global controls currently require internal-system authority.
Operator-only service administration
The three /admin/services/* endpoints use a separate middleware contract:
- The caller’s resolved source IP must match
AKASHA_ADMIN_ALLOWED_IPS; the default allowlist is loopback only. x-akasha-admin-tokenmust match the configured admin token. Missing server configuration fails closed.x-real-ipis considered only when the connection peer is a configured trusted proxy inAKASHA_ADMIN_TRUSTED_PROXIES.
An instance owner’s dashboard session or signed data capability does not automatically confer this host-level access. The customer proxy must not silently convert ordinary requests into daemon-operator authority.
Integration-specific credentials
MIND emissions: /v1/memory/emissions uses a dedicated bearer channel when AKASHA_MIND_EMISSION_TOKEN is configured. The receiver checks that token and validates the emission schema; an optional AKASHA_MIND_ALLOWED_SIGNERS list restricts signer DIDs. Without receiver configuration, the handler fails closed with 503. The payload itself does not carry the original perception-event signature.
Cambium: /v1/cambium/projections and /v1/advice/tools:rank bypass the generic credential layer and call authorize_cambium. These use a configured Cambium bearer token. They are integration endpoints, not general customer data routes.
Probes and transport enforcement
/health/*, /v1/health/*, /v1/lifecycle/status, and /metrics bypass ordinary credential parsing. The global HTTPS requirement, when enabled, is checked before that bypass. Behind a trusted TLS terminator, it requires x-forwarded-proto: https; this check does not itself terminate TLS.
Source: akasha-daemon/src/main.rs (auth_layer, auth_bypass_path, admin_auth_middleware), akasha-daemon/src/capability_auth.rs, akasha-daemon/src/legacy_jwt_auth.rs, akasha-daemon/src/request_authority.rs, akasha-daemon/src/admin_auth.rs, and akasha-daemon/src/mind_receiver.rs. Generated operation references include exact line numbers for the current snapshot.