Access Control

GoodMem uses API keys plus role-based permissions to authorize requests. This page summarizes the authentication flow and how permission failures surface across REST and gRPC.

Authentication

Send the API key in one of these ways:

• CLI: GOODMEM_API_KEY or --api-key.
• REST/gRPC: x-api-key: <api-key>.

Note: We plan to support Authorization: Bearer <api-key> in a future release, but current servers require x-api-key.

If authentication is missing or invalid:

• gRPC returns UNAUTHENTICATED.
• REST returns 401 Unauthorized.

Permissions

Each API method documents its required permission. Permissions typically follow the pattern *_OWN (operate on caller-owned resources) and *_ANY (admin-level access).

If authentication succeeds but the caller lacks the required permission:

• gRPC returns PERMISSION_DENIED.
• REST returns 403 Forbidden.

Administrative RetrieveMemory query-logging policies have their own permissions for create, read, list, and delete operations. See RetrieveMemory Query Logging for the policy model and permission names.

OCR Permission

OCR requests require the OCR_DOCUMENT permission. Missing or invalid credentials yield UNAUTHENTICATED/401, and missing permission yields PERMISSION_DENIED/403. OCR is provided by the GoodMem OCR add-on service/image and is not included in the base install, so requests will fail if the add-on is not enabled even when permissions are present.

See also:

• OCR Output Anatomy