Compliance packs for regulated APIs: PCI-DSS and SOC 2 as code
Compliance packs for regulated APIs: PCI-DSS and SOC 2 as code
Every regulated API I have onboarded followed the same pattern. The team
builds the API, wires up auth, ships to staging, and then someone from
security asks for the compliance checklist. The answers live in a thread.
The fixes come back as rework. The API ships late, or it ships with a
waiver nobody remembers signing.
The fix is not a better checklist. The fix is to stop treating compliance
as a review step and start treating it as config.
One line in the spec
In
api-onboarding-kit,
a consumer declares its compliance baseline the same way it declares its
auth method. One line:
policies: - compliance:pci-dss That line is a bundle, not a flag. It expands into the policies the
baseline actually requires. The PCI-DSS pack expands to JWT auth, a
standard rate limit, and an office IP allowlist. The SOC 2 pack expands
to JWT auth and the standard rate limit. Both packs are owned by the
security team in the policy library, so the team that writes the rules
owns the rules.
The point is boring on purpose. Nobody has to remember what PCI-DSS
means for an API consumer. The bundle remembers.
The validator enforces it
A bundle that only suggests is a checklist with better formatting. So
the validator treats compliance packs as hard rules:
- A compliance pack with API key auth fails validation. PCI-DSS and SOC 2 packs require OAuth2 or mTLS. An API key is not enough, and the lint error says so in plain language.
- A compliance pack going to prod without an IP allowlist policy gets flagged. Staging can be loose. Prod cannot.
Here is the full spec for a payment-adjacent consumer, from the repo
examples:
apiVersion: onboarding/v1 consumer: name: card-processing contact: payments-platform@example.com environments: [staging, prod] traffic: expectedRps: 150 burstRps: 400 auth: method: mtls policies: - compliance:pci-dss certificates: domains: [payments.example.com] autoRenew: true Run the linter on that spec and it passes. Change mtls to apikey
and it fails before anything is rendered. The bad config never reaches
a gateway. That is the whole idea: catch the compliance miss where the
config is written, not in a review meeting three weeks later.
Why a bundle beats a checklist
Three properties matter, and none of them are about the policies
themselves.
Versioned. The pack lives in the policy library, in git. When the
security team tightens the baseline, the change is a commit. Every
consumer that picks up the new library version gets the new rules, and
the diff shows exactly what changed.
Owned. Each pack names an owner. The PCI-DSS and SOC 2 packs belong
to the security team, not to whoever onboarded the last API. If a
consumer team wants an exception, they ask the owner, and the answer
is recorded in the same place as the rule.
Reviewed like code. A change to a compliance pack goes through the
same pull request review as a change to a gateway policy. The security
team reviews the rule once, in the library, instead of reviewing the
same decision separately for every consumer.
What a pack does not do
Honesty matters here. A compliance pack is not certification. PCI-DSS
and SOC 2 each cover far more than gateway config: data handling,
access reviews, incident response, and a long list of controls no
linter can check. The pack covers the API surface only.
What it does give you is evidence. Every render and promotion is
appended to an audit ledger, and onboard history shows it. When an
auditor asks which policies a consumer shipped with and when, the
answer is a log, not a memory. That is a small thing, and it is the
thing auditors actually ask for first.
I wrote a paper on compliance automation for infrastructure back in
2021, and the lesson from that work still holds: the controls that
survive are the ones that run automatically. A control that depends on
someone remembering to check is a control that fails quietly.
The takeaway
Regulated APIs do not need more review meetings. They need the baseline
written down once, owned by the team that understands it, and enforced
by the same pipeline that ships the config. One line in the spec, checked
in CI, logged for the audit. The checklist still exists. It just runs
itself now.