# Authentication and authority How instance credentials, namespaces, actions, service policy, and operator controls fit together. Source: https://docs.minds.sh/docs/api/instance/authentication ## Hosted instance requests [#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. ```http GET /v1/keyspaces HTTP/1.1 Host: your-instance-host x-akasha-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 [#optional-legacy-jwt-verification] When the daemon has a legacy JWT verifier configured, it also requires `Authorization: Bearer `. 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 [#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 [#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-token` must match the configured admin token. Missing server configuration fails closed. * `x-real-ip` is considered only when the connection peer is a configured trusted proxy in `AKASHA_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 [#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 [#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.