Defines the responsibility boundaries for the configuration source of truth, administration APIs, region-local snapshots, emergency blocking, and cache consistency.
8. Data Model
Use the following relational model for the control plane. All primary keys use UUIDs, all times use UTC, and time zones are converted in the presentation layer.
| Table | Key fields | Key constraints |
|---|---|---|
merchants | id, external_ref, name, status, created_at | external_ref is globally unique |
api_keys | id, merchant_id, public_key_id, environment, status, not_before, expires_at, created_at | public_key_id is globally unique; merchant foreign key is non-null |
api_key_secret_versions | id, api_key_id, secret_digest, pepper_version, version, status, valid_from, valid_until | version is unique per Key; no plaintext Secret is stored; Pepper-version foreign key is non-null |
api_key_signing_keys | id, api_key_id, algorithm, public_key, status, valid_from, valid_until | Only approved asymmetric algorithms are allowed; private keys are not accepted |
api_key_client_certificates | id, api_key_id, certificate_fingerprint, issuer_ref, status, valid_from, valid_until | Certificate fingerprint and Key binding are unique; the certificate chain must originate from an approved issuer |
api_key_ip_bindings | id, api_key_id, ip_network, status, created_at | Normalized ip_network is unique under the same Key; overlaps are prohibited; the prefix limits in Section 5.3 are enforced |
scopes | id, scope_name, platform, resource, action, status | scope_name is globally unique |
api_key_scopes | api_key_id, scope_id, granted_at, granted_by | The Key and Scope pair is unique |
routes | id, route_name, environment, platform, method, path_rule, required_scope_id, service_capability_id, request_class, policy_version, status | A database CHECK ensures every published route has a required scope, environment, and service-capability declaration |
merchant_region_policies | merchant_id, environment, primary_region, allowed_regions, failover_mode, version | Only one effective policy exists for every merchant and environment |
service_capabilities | id, service_name, environment, read_consistency, max_replication_lag_ms, signal_max_age_seconds, supports_global_idempotency, automatic_read_failover, automatic_write_failover | Only one effective capability declaration exists for every service and environment; capability expansion requires approval |
service_endpoints | id, service_name, environment, region, endpoint_ref, health_policy, status | The service, environment, region, and endpoint reference combination is unique |
control_plane_epochs | epoch, writer_region, lease_id, activated_at, fenced_previous_writer_at | Append-only; evidence of former-primary fencing must be recorded before takeover |
config_outbox | id, aggregate_type, aggregate_id, config_epoch, config_sequence, event_type, payload, published_at | Event ID is unique; written in the same transaction as the configuration change; versions are compared by epoch and sequence |
admin_audit_logs | id, actor_id, action, resource_type, resource_id, before_digest, after_digest, reason, created_at | Append-only; updates and deletes are prohibited |
Use PostgreSQL inet type for IP addresses. secret_digest, audit differences, and Outbox payloads require column-level encryption or disk encryption; no payload may contain a plaintext Secret.
9. Administration Interfaces
Administrative interfaces are accessible only from the internal administration network and use short-lived access tokens issued by the company identity system. Provide the following fixed resource interfaces:
| Method and path | Purpose | Key inputs |
|---|---|---|
POST /admin/v1/api-keys | Create a Key | merchant_id, environment, scopes, ip_bindings, expires_at, reason |
GET /admin/v1/api-keys | Query Key metadata by merchant, status, or environment | Query criteria; does not return Secret or digest |
POST /admin/v1/api-key-rotations | Create a new Secret version | api_key_id, overlap_hours, reason |
POST /admin/v1/api-key-signing-keys | Register a merchant request-signing public key | api_key_id, algorithm, public_key, valid_until, reason |
POST /admin/v1/api-key-client-certificates | Bind an mTLS client certificate | api_key_id, certificate_fingerprint, issuer_ref, valid_until, reason |
POST /admin/v1/api-key-suspensions | Suspend a Key | api_key_id, reason |
POST /admin/v1/api-key-revocations | Permanently revoke a Key | api_key_id, reason |
PUT /admin/v1/api-key-ip-bindings | Atomically replace the IP-binding set for one Key | api_key_id, ip_bindings, expected_version, reason |
PUT /admin/v1/api-key-scopes | Atomically replace the Scope set for one Key | api_key_id, scopes, expected_version, reason |
POST /admin/v1/routes/validations | Validate route configuration pending publication | Full route configuration and target version |
POST /admin/v1/route-publications | Publish a validated route version | route_id, expected_version, reason |
Every write interface must support an idempotency request identifier, an optimistic-lock version, and an operation reason. Responses that atomically replace IPs or Scopes must return both the digest of the pre-replacement set and the new version number for incorrect-operation audit and controlled rollback. Secret-creation responses must not be recorded by reverse proxies, APM, or audit middleware.
High-risk operations include production Key creation, Scope privilege escalation, IP-range expansion, enabling cross-region writes, and changing revocation-restoration policy. These operations should require dual approval.
10. Cache and Configuration Consistency
10.1 Configuration Publishing and Operations Center
The Configuration Publishing and Operations Center has two independent paths. Ordinary changes flow through the single-writer control plane, PostgreSQL, and the Outbox. The emergency deny-only path uses a separate network, identity role, and hardware-protected signature, so it can still restrict access when the ordinary control plane is unavailable. Immutable audit writes belong to this boundary; the Observability Center only reads and correlates those records.
The ordinary publishing flow is:
- The control plane updates configuration and writes an Outbox event in the same PostgreSQL transaction.
- A publisher sends the event to the message bus. The event contains the
(epoch, sequence)configuration version. - Consumers in every region apply events idempotently, comparing
epochbeforesequenceand rejecting an old version that would overwrite a new version. - The API Key validation service in every region maintains a Redis snapshot and a short in-process cache.
- Every region periodically performs full version reconciliation and rebuilds a snapshot from the source of truth after it discovers a gap.
10.2 Revocation Priority
Revocations, suspensions, and IP removals are security events. They must use a high-priority path and push invalidation notifications to every region. The recommended target is that 99.9% of security changes take effect within 10 seconds.
If the message bus fails, regions use short-interval version polling as compensation. For a new Key or uncached Key whose state cannot be confirmed, the data plane must reject it; authorization must not be bypassed for availability.
10.3 Emergency Deny-Only Channel
When the control plane or PostgreSQL is unavailable, security personnel must still be able to block a leaked Key immediately. Every region provides an independent break-glass emergency blocking ingress and follows these constraints:
- The ingress may only add deny entries for a public Key ID, merchant ID, or source IP. It cannot add allow entries, expand permissions, or delete a central revocation record.
- Instructions are signed by a hardware-protected internal security-signing key. The API Key validation service in every region first verifies the signature, then unions deny entries with central configuration.
- Under normal conditions, approval from two authorized security personnel is required. A declared highest-severity security incident permits the incident commander to act first, but a second approver must review within 15 minutes.
- The initial lease period for a regional local deny entry is 24 hours. If the control plane remains unavailable, security personnel can renew it through the same signing and approval process. The API Key validation service alerts two hours and one hour before expiry, and must not automatically restore an allow decision merely because the lease expires while the control plane is unavailable and the deny entry has not been formally archived. After control-plane recovery, the entry must be converted into a formal suspension or revocation record; it must not be removed early before archival is complete.
- Every region writes the actor, approver, reason, signature digest, receipt time, and effective time to local append-only audit storage.
- The break-glass ingress uses a network path, identity role, and signing key distinct from the ordinary Gateway Admin API, and is exercised once per quarter.
10.4 Degradation Strategy
| Failure | Behavior |
|---|---|
| PostgreSQL control-plane primary database unavailable | Stop ordinary management writes; the data plane continues with the last verified snapshot; emergency blocking uses the channel in Section 10.3 |
| Message bus unavailable | The control plane commits configuration but marks it pending publication; regions compensate through version polling; do not declare a change effective before publication completes |
| Regional Redis unavailable | The API Key validation service uses a bounded in-process snapshot; unknown Keys and Keys beyond snapshot validity are denied. Distributed rate limiting degrades to per-instance token buckets. An instance may use only quota shares leased before the failure and not yet expired, while a new instance gets zero quota; therefore, the sum of shares across all instances must not exceed the merchant's or Key's global quota |
| API Key validation service unavailable | Gateway authentication fails closed and returns 503; authorization validation is not bypassed |
| One backend instance unavailable | Health checking removes it and selects a healthy instance in the same service pool |
| Entire backend region unavailable | Decide failover or return 503 according to the read and write preconditions in Section 7.3 |
The recommended maximum offline-use time for the last verified snapshot is 15 minutes. If no newer version is available after that period, reject high-risk write requests; whether read requests may continue must be confirmed by every platform according to its risk classification.