OrgSecurityKeysService

Exposes per-organization secret key material to internal services that need it for HMAC computation, signature verification, or envelope-key derivation.

Caution

This is an internal service. Every RPC returns raw key material, so it is restricted to authenticated internal service-to-service callers and is not exposed to external clients. It cannot be called with a user JWT.

Methods

Method	Description
GetPeppers	Return all non-retired pepper versions for one (org, purpose)

GetPeppers

Return all non-retired pepper versions for one (org_id, purpose) pair, in ascending version order. During a rotation overlap window multiple versions are returned — callers compute lookup hashes under every returned version so lookups keep matching across the rotation. Typically the response contains exactly one entry; two during a rotation overlap window; zero only when no pepper has ever been generated for the pair (success with an empty list — the caller decides whether absence is a hard error).

An empty or non-UUID org_id, or an empty purpose, is rejected with INVALID_ARGUMENT.

Authorization: Internal service only

Request: GetPeppersRequest

Field	Type	Description
org_id	string	Organization whose peppers are requested.
purpose	string	Purpose identifier scoping which key family to return (e.g. reachability_lookup for the reachability registry lookup hash).

Response: GetPeppersResponse

Field	Type	Description
peppers	Pepper[]	All non-retired pepper versions for the (org, purpose) pair, in ascending version order.

Pepper

Field	Type	Description
version	int32	Monotonically-increasing version number. Lower versions retire first.
key_material	bytes	Raw HMAC key material. Sensitive — callers must not log or persist this value to disk. In-memory caching keyed on (org, version) with a short TTL is permitted and expected.