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.

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