---
id: WF-PFM-SEC-008
title: Flush the gateway's cached decisions
trigger: A committed security change or registry activation requests faster cache turnover.
product_area: platform
module: security
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
- CAP-PFM-SEC-015
- CAP-PFM-SEC-009
- CAP-PFM-SEC-010
- CAP-PFM-SEC-012
- CAP-PFM-SEC-017
crosses:
- SVC-PFM-SEC-security
- SVC-PFM-SEC-tenants
idempotency: Each new change receives a new submission identity; retrying that submission returns its job.
  Repeating the gateway reset is intended to converge, but reported success alone does not prove eviction.
concurrency: Flush jobs may overlap and do not share an open-job exclusion. The task attempts every configured
  API stage and aggregates failures before returning.
hops:
- n: 1
  actor_or_service: The changing capability (after commit)
  action: Persist and submit a flush job with the change reason.
  anchor: services-platform:modules/security/services/authorizer-flush/submit-flush-job.ts
  seam: sync
  on_failure: Log submission failure without rejecting the already committed security change.
  left_inconsistent: Previously evaluated decisions remain within their cache lifetime.
  observer: Flush job reads and submission logs show the attempt.
  provenance: observed
  source: services-platform:modules/security/services/authorizer-flush/submit-flush-job.ts (header)
- n: 2
  actor_or_service: Flush job (one step)
  action: Read configured API stages and request an authorizer reset for each.
  anchor: services-platform:modules/security/services/authorizer-flush/flush-stages.ts
  seam: state_machine
  on_failure: Retry aggregate transient failures briefly; malformed or absent configuration is refused.
  left_inconsistent: Unflushed stages retain earlier decisions until expiry.
  observer: The job records stage counts and errors.
  provenance: observed
  source: services-platform:modules/security/services/authorizer-flush/flush-stages.ts (header)
- n: 3
  actor_or_service: API Gateway
  action: Ask each gateway stage to evict its cached decisions.
  anchor: API Gateway FlushStageAuthorizersCache
  seam: sync
  on_failure: A reset can report success while a cached decision still serves traffic.
  left_inconsistent: Earlier decisions can survive the sixty-second cache interval, with signed contexts separately
    bounded.
  observer: Observed subsequent authorization and the flush job provide evidence beyond the reset response.
  provenance: documented
  source: services-platform:docs/security/authorizer-cache-flush.md#What the system does today
branches:
- Release activation reports a flush failure without rolling back the active release.
waits:
- The flush retry policy is short; the sixty-second gateway cache lifetime remains the consistency fallback.
evidence:
- 'services-platform at ad3f6a65: modules/security/services/authorizer-flush/*; scripts/flush-authorizer.ts;
  aws/logic/security-authorizer-flush.step-function.ts; docs/security/authorizer-cache-flush.md.'
examined_at: '2026-10-23'
examiner: codex
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Flush the gateway's cached decisions

## What It Does

Flushing accelerates eventual consistency but does not establish immediate revocation. The workflow records submission, configured-stage iteration and the gateway reset result separately.

## The Flow

```mermaid
flowchart TD
    H1["Submit flush job"]
    H2["Reset configured stages"]
    H3["Observe actual eviction"]
    H1 --> H2
    H2 --> H3
```

The diagram separates the relevant success, alternative and failure paths. The numbered hop rows retain the detailed authority checks, delegated work and retry limits.

## When Something Fails

Acceptance proof must include traffic after the reset; a successful provider response alone is insufficient. Previously issued signed contexts retain their own validity bound.

Each new change receives a new submission identity; retrying that submission returns its job. Repeating the gateway reset is intended to converge, but reported success alone does not prove eviction.

Flush jobs may overlap and do not share an open-job exclusion. The task attempts every configured API stage and aggregates failures before returning.

## Open Design Questions

The recorded findings retain any stronger planning expectation, missing writer or unproved recovery path. Observed behavior does not approve those outstanding product choices.