Apikey

Services

ApiKeyService Service

Service for managing API Keys in the GoodMem system.

Authentication: gRPC metadata x-api-key: <api-key>

Global errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Authorization model:

• Create, update, and delete RPCs evaluate a typed authorization operation against the target API key and its administrative owner.
• Listing first requires LIST_API_KEY on the singleton instance, then returns only credentials passing READ_API_KEY under the authenticated principal's effective authorization policy.

CreateApiKey

Creates a new API key for an active principal.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: CREATE_API_KEY on the proposed credential, evaluated using its proposed administrative owner.

Summary:

• The raw API key is returned ONLY in this response; client MUST save it immediately
• Once the response is processed, the raw key material is never accessible again
• Omitted subject and mode preserve the self-issued human inheriting-key behavior
• SERVICE subjects require SCOPED plus a nonempty immutable ceiling
• Every ceiling descriptor must be conservatively covered by both the subject's live authority and the issuing credential's effective authority
• A scoped issuing credential may issue only another scoped credential; it cannot mint an inheriting credential that escapes its immutable ceiling
• New keys start in ACTIVE status unless their validity window says otherwise
• ALREADY_EXISTS: if client-provided api_key_id is already in use

Side Effects:

• Persists API key; generates cryptographically secure key material; sets audit fields

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks create/subject authority, exceeds the issuing credential's effective authority, or a scoped credential attempts to issue an inheriting credential
• INVALID_ARGUMENT: malformed mode, ceiling, validity window, or labels
• NOT_FOUND: requested subject or assigned ceiling resource does not exist
• FAILED_PRECONDITION: deleted subject or unsupported subject/mode combination
• ALREADY_EXISTS: client-provided api_key_id already exists
• INTERNAL: unexpected server error

Idempotency: Non-idempotent; clients SHOULD NOT blindly retry on unknown failures.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{
"labels": {"env": "dev", "service": "backend"}
}' \
localhost:8080 goodmem.v1.ApiKeyService/CreateApiKey

Note: bytes fields in JSON must be base64.

GetApiKey

Retrieves one API key by UUID with its complete immutable ceiling.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: READ_API_KEY on the existing credential, evaluated under the caller's live authority and any scoped-key ceiling.

Response: Complete non-secret metadata with ceiling_omitted=false. Raw and hashed key material are never returned.

Side Effects: None.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: api_key_id is not one UUID.
• NOT_FOUND: The credential does not exist. Existence is resolved before authorization.
• PERMISSION_DENIED: Caller lacks effective READ_API_KEY on the existing credential.
• INTERNAL: Unexpected authorization or database failure.

Idempotency: Read-only and safe to retry.

ListApiKeys

Lists API keys discoverable to the authenticated principal.

Auth: gRPC metadata x-api-key: <api-key>

Authorization: Requires LIST_API_KEY on the singleton instance. Each returned row must independently pass READ_API_KEY on that credential. Both gates use the caller's live authority intersected with any scoped authenticating-key ceiling.

Summary:

• Returns one page of metadata for API keys discoverable to the caller
• Results use stable API-key UUID order
• FULL is the default view and includes complete ceilings; its page size defaults to 10 and may not exceed 20. BASIC omits ceilings, defaults to 50, and may not exceed 1,000.
• Subject, owner, and lifecycle filters are applied in PostgreSQL after authorization and never broaden result visibility.
• Lifecycle is evaluated at current server time independently for each page. Credentials can cross lifecycle boundaries between page requests; clients must tolerate the resulting change in filter membership.
• next_token is opaque and binds every stable filter, the resolved view, and the complete authentication context. It never accepts a caller-controlled lifecycle evaluation instant.
• Raw key material and key hashes are never included in responses

Side Effects: None

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• INVALID_ARGUMENT: malformed UUID filter, unspecified/unknown lifecycle or view, invalid page size for the resolved view, or mismatched/malformed continuation token
• PERMISSION_DENIED: caller lacks effective LIST_API_KEY on the singleton instance
• INTERNAL: unexpected server error

Idempotency: Read-only; safe to retry; results may change over time.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{}' \
localhost:8080 goodmem.v1.ApiKeyService/ListApiKeys

UpdateApiKey

Updates mutable properties of an API key.

Auth: gRPC metadata x-api-key: <api-key>

Permissions Required:

• Label changes require UPDATE_API_KEY
• Setting status=INACTIVE requires DELETE_API_KEY
• A combined label-and-deactivation request requires both operations

Summary:

• Mutable fields: status, labels
• Immutable fields: api_key_id, subject_principal_id, key material, created_at, and created_by_id
• Label updates support replace (clear all, set new) or merge (upsert) strategies
• Revocation is one-way; status=ACTIVE cannot reactivate an inactive key

Side Effects:

• Persists changes; updates updated_at and updated_by_id

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks an operation represented by the requested fields
• INVALID_ARGUMENT: invalid api_key_id format; both label strategies set; STATUS_UNSPECIFIED provided; no updatable fields
• FAILED_PRECONDITION: attempts to reactivate a revoked key
• NOT_FOUND: API key does not exist
• INTERNAL: unexpected server error

Idempotency: Idempotent with identical input; safe to retry.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{
"api_key_id": "BASE64_UUID_BYTES_HERE",
"status": "INACTIVE"
}' \
localhost:8080 goodmem.v1.ApiKeyService/UpdateApiKey

Note: bytes fields in JSON must be base64.

DeleteApiKey

Permanently revokes an API key.

Auth: gRPC metadata x-api-key: <api-key>

Permissions Required: DELETE_API_KEY

Summary:

• This operation is irreversible and immediately invalidates the key
• The durable credential and audit history remain stored
• UpdateApiKey with status=INACTIVE performs the same protected lifecycle transition

Side Effects:

• Records permanent revocation time and actor; invalidates future authentication

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks DELETE_API_KEY
• INVALID_ARGUMENT: invalid api_key_id format
• NOT_FOUND: API key does not exist
• INTERNAL: unexpected server error

Idempotency: Safe to retry; may return NOT_FOUND if already deleted or never existed.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{ "api_key_id": "BASE64_UUID_BYTES_HERE" }' \
localhost:8080 goodmem.v1.ApiKeyService/DeleteApiKey

Note: bytes fields in JSON must be base64.

Messages

ApiKey

Represents an API key for authenticating requests to the GoodMem service.

API keys authenticate durable HUMAN or SERVICE principals and provide secure, token-based authentication for both gRPC and REST API endpoints. Each key separates its authenticated subject from its administrative owner and immutable issuance authority.

Security:

• key_hash and raw key material are never included in API responses.
• The raw API key is only returned once during creation via CreateApiKeyResponse.
• Key material is cryptographically hashed using secure algorithms.
• Authentication validates valid_from, expires_at, and permanent revocation state.

Lifecycle:

• Setting status to INACTIVE permanently revokes a key.
• DeleteApiKey performs the same permanent revocation while retaining durable audit metadata.
• Keys automatically become invalid after expires_at (if set).
• Active keys with no expiration remain valid indefinitely.

Immutability:

• api_key_id is the immutable primary identifier.
• Subject, authority mode, validity window, and ceiling are fixed at issuance and cannot be modified.

Notes:

• All timestamps are UTC (google.protobuf.Timestamp).

See also: goodmem.v1.ApiKeyStatus

ApiKey.LabelsEntry

CreateApiKeyRequest

CreateApiKeyRequest.LabelsEntry

CreateApiKeyResponse

Response for CreateApiKey containing the one-time raw key.

Security:

• raw_api_key is returned ONLY in this response
• Client MUST save the raw key immediately; it cannot be retrieved again

GetApiKeyRequest

Request to retrieve one API-key resource by UUID.

GetApiKeyResponse

Response containing complete non-secret API-key metadata.

ListApiKeysRequest

ListApiKeysResponse

ListApiKeysNextPageToken

Opaque API-key page cursor encoded and validated by the server.

UpdateApiKeyRequest

DeleteApiKeyRequest

Enums

ApiKeyStatus

API key status for lifecycle management.

• STATUS_UNSPECIFIED = 0: Invalid status; never used in practice
• ACTIVE = 1: Key is valid and can be used for authentication
• INACTIVE = 2: Key cannot authenticate at the response evaluation instant because it is not yet valid, has expired, or was permanently revoked

ApiKeyLifecycleState

Precise API-key lifecycle derived at one server-selected evaluation instant.

Precedence is REVOKED, then NOT_YET_VALID, then EXPIRED, then USABLE. valid_from is inclusive and expires_at is exclusive. This enum supplements the compatibility ApiKeyStatus, whose INACTIVE value combines every currently unusable state.

ApiKeyView

Metadata projection returned by ListApiKeys.

ApiKeyAuthorityMode

Determines how an API key derives its effective authorization.

An inheriting key follows the live authority of its HUMAN subject. A scoped key intersects the subject's live authority with the immutable, nonempty ceiling selected when the key is issued.