API Security Policy Builder

This policy sets the minimum security requirements for every API that Kestrel Pay designs, builds, operates or consumes, so that APIs are inventoried, authenticated, authorised, monitored and tested to a consistent standard aligned with the OWASP API Security Top 10 2023.

1. 1.1Scope. The policy applies to all public, partner and internal APIs built with REST, GraphQL and gRPC (between 51 and 200 APIs at the time of writing), in every environment that is reachable by a consumer, including APIs built by contractors and APIs hosted by a provider on Kestrel Pay's behalf. Third-party APIs that Kestrel Pay calls are covered by section 13.
2. 1.2The key words MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119. A SHOULD that is not met is recorded with a reason; a MUST that is not met needs an approved exception (section 16).
3. 1.3Policy owner: Chief Information Security Officer (CISO). Approves this policy and high-risk exceptions, and reports compliance to leadership.
4. 1.4API owner: a named person (not a team alias) for each API, accountable for its inventory record, its specification, remediation of findings and its retirement.
5. 1.5Application security: runs design reviews, maintains the standards appendix and the testing programme, and triages findings.
6. 1.6Platform / API gateway team: operates the API gateway, the configuration baselines and the shared authentication and rate-limiting components.
7. 1.7Security operations: monitors API telemetry, investigates alerts and leads API incident response.
8. 1.8Data protection / privacy lead: advises on data minimisation and on APIs that process personal data.
9. 1.9Compliance: maintains the mapping between this policy and the regulatory context tagged for Kestrel Pay (PCI DSS, GDPR, PSD2, SOC 2). The tags indicate which frameworks compliance considers; this policy does not interpret or claim to satisfy any of them.
10. 1.10Risk tier. Based on the answers that shaped it, this policy is written for a high risk tier. The tier sets the default cadences, lifetimes and deadlines used throughout; Chief Information Security Officer (CISO) may tighten them for individual APIs.

Shaped by: Tier: HighPublic APIsPartner APIsInternal APIs51-200 APIsTag: PCI DSSTag: GDPRTag: PSD2Tag: SOC 2

You cannot protect an API nobody knows exists. The inventory is the system of record that every other section depends on.

1. 2.1Every API MUST be recorded in the API inventory before it receives production traffic. Each record holds: name, API owner, exposure (public, partner, internal), style, environments and hostnames, version(s) in service, authentication method, consumers, the highest data classification it handles, specification location and lifecycle status.
2. 2.2Every API MUST have a machine-readable specification kept in source control next to the code: an OpenAPI 3.x description, a GraphQL schema (SDL) and gRPC .proto files. The deployed API MUST match its specification; undocumented endpoints, fields or methods are defects.
3. 2.3With between 51 and 200 APIs, the inventory MUST be reconciled automatically against gateway configuration, traffic logs and cloud or DNS records at least monthly. Anything found in traffic but missing from the inventory is treated as a shadow API and assigned an owner within 10 working days.
4. 2.4An API without an owner for 30 days is escalated to Chief Information Security Officer (CISO) and scheduled for decommissioning.
5. 2.5Each API's data classification records whether it handles personal data, payment data or secrets. That classification drives authentication strength (section 4), data exposure rules (section 7) and logging (section 14).
6. 2.6For each partner or third-party consumer, the inventory records which APIs and scopes they can use and which data leaves Kestrel Pay through them.

Shaped by: 51-200 APIsRESTGraphQLgRPCExternal consumers

Most API flaws are design decisions, so security review happens before the code is written and again when the design changes.

1. 3.1A new API, or a material change to an existing one, MUST have a design review that includes a threat model covering each OWASP API Security Top 10 2023 risk relevant to the design.
2. 3.2Review triggers: new public or partner exposure; a new data classification (especially personal data, payment data or secrets); a new authentication method; a new outbound call capability; a new third-party integration; a new sensitive business flow.
3. 3.3Every public or partner API, and every API handling the highest data classifications, MUST have Application Security sign-off before go-live. Internal APIs complete the review checklist and Application Security samples at least one in five.
4. 3.4Each operation in the specification MUST declare its security scheme, required scopes or roles, and rate-limit tier, so the reviewer and the gateway read the same source of truth.
5. 3.5GraphQL designs MUST state the maximum query depth, the complexity budget, whether introspection is available and where field-level authorisation is enforced.
6. 3.6gRPC designs MUST state how callers are authenticated per channel, how per-method authorisation is enforced, and whether server reflection is enabled in any environment.

Shaped by: Tier: HighGraphQLgRPC

Authentication answers "who is calling". Each mechanism you use gets its own rules; mechanisms you do not use are not mentioned.

1. 4.1Every endpoint MUST require authentication unless it is listed as anonymous in the inventory with a reason (for example a health check or a public catalogue). Anonymous endpoints MUST NOT return personal or confidential data.
2. 4.2Internal APIs MUST authenticate their callers too. Network location (a private subnet, a VPN, a service mesh without identity) is not authentication.
3. 4.3OAuth 2.0 / OIDC: user-facing clients MUST use the authorization code flow with PKCE; machine clients MUST use client credentials. The implicit and resource owner password credentials grants MUST NOT be used.
4. 4.4Resource servers MUST validate the access token's signature, issuer, audience, expiry and scopes on every request. Access tokens MUST expire within 15 minutes. Refresh tokens MUST be rotated on use and revoked on logout and on suspected compromise.
5. 4.5Tokens that can initiate payments or change account security settings SHOULD be sender-constrained (DPoP or mutual-TLS-bound tokens) so a stolen token cannot be replayed from another client.
6. 4.6JWT: verifiers MUST allowlist the expected signing algorithms and reject "none"; MUST NOT fetch keys from URLs or keys carried in the token header (jku, x5u, jwk) unless the source is allowlisted; MUST check exp and nbf with no more than 60 seconds of clock skew; and MUST validate iss and aud. JWT payloads are encoded, not encrypted, and MUST NOT carry secrets or unnecessary personal data.
7. 4.7API keys identify a calling application, not a user. They MUST NOT be the only control protecting endpoints that return personal data, payment data or secrets; combine them with OAuth 2.0 or mutual TLS there.
8. 4.8API keys MUST be scoped to the APIs and operations the consumer needs, stored only as salted hashes on the server side, never accepted in URLs or query strings, and rotated at least every 90 days. Revocation MUST take effect within 15 minutes.
9. 4.9Mutual TLS: client certificates MUST be issued by a Kestrel Pay-controlled or contractually agreed CA, live no longer than 90 days with automated renewal, and be mapped to a specific client identity (subject or SAN) that authorisation then uses. A valid certificate alone MUST NOT grant access to every API.
10. 4.10Endpoints that accept credentials or one-time codes (login, token, password reset, OTP verification) MUST resist brute force and credential stuffing: per-account and per-source throttling, lockout or progressive delay, and alerting.
11. 4.11Each partner MUST have its own credentials. Credentials MUST NOT be shared between partners or between a partner and a first-party app.
12. 4.12Third-party developers MUST register each application, accept the developer terms and receive per-application credentials with the narrowest scopes their use case needs. Scope requests above the default tier are reviewed.
13. 4.13Secrets used by APIs (signing keys, client secrets, API keys, database passwords) MUST live in a secrets manager, never in source code, images or client-side bundles. Secret scanning MUST run on every repository.

Shaped by: OAuth 2.0 / OIDCAPI keysMutual TLSJWT (self-issued or IdP)Internal APIsPartnersThird-party developers

Authorisation answers "may this caller do this, to this object". Missing object-level checks (API1) and function-level checks (API5) are the most common serious API flaws.

1. 5.1Object level (API1). Every operation that receives an object identifier (path, query, body or header) MUST check that the authenticated caller may access that specific object, on every request, in the code path that loads it. Identifiers supplied by the client are never proof of ownership.
2. 5.2Object identifiers SHOULD be random and non-sequential (for example UUIDs). This is defence in depth only; it does not replace the check.
3. 5.3Tenant isolation: tokens and keys issued to a partner or third-party application MUST only reach objects that belong to that tenant or to users who granted that application consent. Cross-tenant access is tested on every release.
4. 5.4GraphQL: authorisation MUST be enforced in resolvers for every object and field, including nested objects reached through relationships, not only at the endpoint.
5. 5.5gRPC: authorisation MUST be enforced per method (for example in a server interceptor), using the authenticated peer or token identity.
6. 5.6Function level (API5). Access is deny-by-default: an operation with no declared role or scope is rejected. Role and scope checks MUST be enforced server-side, in shared middleware or at the gateway, not in client applications.
7. 5.7Administrative and privileged functions MUST be separated from consumer functions (separate routes or services, separate scopes) and MUST NOT be reachable by consumer credentials. Changing the HTTP method or path casing MUST NOT bypass a check.
8. 5.8Scopes that can move money or change payout details MUST be distinct from read scopes and MUST NOT be granted to third-party applications by default.
9. 5.9Every API MUST have automated authorisation tests that call each operation as at least two users of each role and as an unauthenticated caller, and assert the expected allow or deny.

Shaped by: Multi-tenant consumersGraphQLgRPCPayment data

The specification is the contract; requests that break it are rejected before business logic runs.

1. 6.1Requests MUST be validated against the published specification at the gateway or in the service framework: types, formats, lengths, ranges, enumerations and required fields.
2. 6.2Unknown properties MUST be rejected or ignored, never bound to internal objects. Properties the caller may not set (role, balance, status, owner identifiers, prices) MUST be excluded from writable models. This blocks mass assignment (API3).
3. 6.3Request bodies, headers, arrays and uploaded files MUST have maximum sizes (API4). The Content-Type MUST be checked, and parsers MUST be configured safely (for example XML external entity resolution disabled).
4. 6.4Injection is not a separate item in the 2023 list but stays in scope: data access MUST use parameterised queries or safe ORM methods, and output MUST be encoded for its context.
5. 6.5GraphQL: enforce maximum query depth, a complexity or cost budget, limits on aliases and batched operations, and a timeout. First-party public clients SHOULD use persisted (allowlisted) queries.
6. 6.6gRPC: set maximum receive message sizes and deadlines on every method, and validate fields explicitly (proto3 default values cannot distinguish "not sent" from zero or empty).

Shaped by: GatewayGraphQLgRPC

Return only what the caller is allowed to see. Filtering in the client is not a control.

1. 7.1Responses MUST be built from explicit response schemas listing the properties each role may read. Serialising whole internal objects or database rows and relying on the client to hide fields MUST NOT be used.
2. 7.2Property-level authorisation applies to reads and writes: a caller who may read an object may still be forbidden from reading or changing some of its properties.
3. 7.3Personal data: return the minimum needed for the use case, mask by default (for example partial email or phone), and return full values only to roles that need them and only on endpoints flagged in the inventory.
4. 7.4Payment data: full card numbers MUST NOT be returned by any API outside the designated cardholder data environment; return a token or the last four digits. Card verification codes MUST NOT be stored or returned after authorisation. Bank account details are masked except on payout-management endpoints.
5. 7.5Credentials and secrets MUST NOT be returned by any API after creation. A newly created secret is shown once; afterwards only its identifier, prefix and creation date.
6. 7.6Error responses MUST be generic to the caller (no stack traces, SQL, internal hostnames or library versions) and carry a correlation ID that maps to the detailed server-side log.
7. 7.7Sensitive values MUST NOT appear in URLs or query strings, because these are logged by proxies and browsers.
8. 7.8All APIs MUST use TLS 1.2 or later (TLS 1.3 preferred), including internal service-to-service calls. Public APIs MUST send HSTS. Responses containing sensitive data MUST send Cache-Control: no-store.

Shaped by: Personal data (PII)Payment card / account dataCredentials and secrets

Every API call costs CPU, memory, bandwidth or money. Limits stop one caller from exhausting them, by accident or on purpose.

1. 8.1Every public and partner API MUST enforce rate limits per consumer identity (token, key or certificate) and, for unauthenticated traffic, per source address. Limits are defined per tier in the standards appendix and declared in the specification.
2. 8.2Every API MUST bound the work a single request can cause: maximum page size on list endpoints, maximum records per batch, execution timeouts, and maximum upload size.
3. 8.3GraphQL cost limits (section 6) count toward the consumer rate limit, so one expensive query cannot do the work of thousands of cheap ones.
4. 8.4Operations that trigger paid third-party actions (SMS, email, voice, identity verification, data enrichment) MUST have per-consumer and global spend caps with alerts.
5. 8.5Callers over a limit MUST receive HTTP 429 (or gRPC RESOURCE_EXHAUSTED) with a Retry-After hint. Limit breaches are logged (section 14).
6. 8.6Internal APIs MUST set quotas and timeouts between services so one failing or noisy service cannot cascade.
7. 8.7Third-party developer applications start on the lowest tier; higher tiers are granted on request with a stated use case.

Shaped by: External exposureGraphQLThird-party developers

Some flows hurt the business when automated at scale even though each single call is legitimate. Technical rate limits alone do not stop that.

1. 9.1The following flows are designated sensitive and MUST be marked in the inventory, each with a documented abuse case and owner: account sign-up; login and account recovery (including OTP); payments and transfers; referral and promo redemption.
2. 9.2Each sensitive flow MUST have business-level limits in addition to technical rate limits: per-account and per-device velocity, and alerts on unusual volume or patterns.
3. 9.3Sensitive flows exposed publicly MUST include automation detection (device signals, behavioural checks or challenge) proportionate to the abuse case, and SHOULD prefer silent signals over challenges for legitimate users.
4. 9.4Payments and transfers: step-up authentication for new payees and for amounts above a defined threshold, idempotency keys so a retried request cannot execute twice, per-account transaction limits, and an out-of-band notification to the account holder.
5. 9.5Account sign-up: limit accounts per device and per verified contact, and detect disposable or patterned identities.
6. 9.6Login, password reset and OTP: responses MUST NOT reveal whether an account exists, and OTP verification MUST have a small attempt limit per code.
7. 9.7Referral and promotions: one redemption per eligible account, rewards held until a qualifying action, and monitoring for clusters of linked accounts.
8. 9.8Flow owners review abuse metrics with the fraud or product owner at least quarterly.

Shaped by: Account sign-upLogin, password reset, OTPPayments and transfersReferral or promo redemption

When an API fetches a URL on a caller's behalf, the request starts inside your network. SSRF turns that position against you.

1. 10.1Any API that makes a server-side request to a URL influenced by a caller (webhook delivery) MUST send it through a hardened egress component, not an ordinary HTTP client.
2. 10.2That component MUST: allow only https (and http only where approved); resolve the hostname and reject destinations in loopback, private (RFC 1918), link-local (169.254.0.0/16, including cloud metadata addresses), carrier-grade NAT, multicast, reserved and the IPv6 equivalents; connect to the validated address so DNS cannot rebind between check and connect; disable redirects or re-validate every hop; and apply connect and read timeouts and a response size cap.
3. 10.3The raw response of an outbound fetch MUST NOT be returned to the caller unless the feature requires it; return a status or a sanitised result instead.
4. 10.4Webhooks: destinations MUST be validated when registered and again at delivery; payloads MUST be signed (for example HMAC with a per-subscriber secret and a timestamp) so receivers can verify them; retries are bounded with backoff.
5. 10.5API workloads MUST run with network egress restricted to the destinations they need, enforced at the network layer, so an application-layer bypass does not reach the internal network.
6. 10.6Cloud workloads MUST require the token-based instance metadata service (for example AWS IMDSv2) and SHOULD block metadata access entirely for workloads that do not need it.

Shaped by: Sends webhooks to customer URLsCalls other internal services onlyPublic cloud

Misconfiguration is the gap between a secure design and what is actually deployed.

1. 11.1Each component in the API path (gateway, load balancer, web server or runtime, framework, container, cloud account) MUST follow a documented hardening baseline kept as code and checked automatically in the deployment pipeline. Drift from the baseline raises an alert.
2. 11.2All public and partner traffic MUST pass through the API gateway. APIs not yet behind it are listed in the inventory with a migration date agreed with the policy owner, and are tracked as exceptions until then.
3. 11.3Only the HTTP methods an operation needs are enabled. CORS MUST use an explicit allowlist of origins and MUST NOT combine a wildcard origin with credentials. Security headers are set per the standards appendix.
4. 11.4Debug modes, verbose errors, sample apps, default credentials and management endpoints (metrics, admin consoles, framework actuators) MUST be disabled or not reachable from consumer networks in production.
5. 11.5GraphQL: introspection and field suggestions MUST be disabled in production unless the schema is deliberately published for the developer programme.
6. 11.6gRPC: server reflection MUST be disabled in production.
7. 11.7Vulnerabilities in internet-facing API components MUST be fixed within 7 days (critical) and 30 days (high); internal components within twice those times.
8. 11.8Non-production environments MUST NOT be reachable from the internet without authentication and MUST NOT hold production personal or payment data.

Shaped by: Some APIsTier: HighGraphQLgRPC

Old versions and forgotten hosts are where attackers find the endpoint that missed the fix.

1. 12.1Every API MUST use a documented versioning scheme (REST: a major version in the path or a header; GraphQL: additive evolution with @deprecated fields; gRPC: versioned packages). Breaking changes require a new major version.
2. 12.2Consumers MUST receive at least 12 months' notice before a version is retired, through the developer portal or partner contact and a Deprecation or Sunset response header.
3. 12.3Security fixes MUST be applied to every version still in service. If a fix cannot be backported, the old version is retired on an expedited schedule approved by the policy owner.
4. 12.4Retired versions MUST be removed from the gateway, DNS, load balancers and code, not just from documentation. The inventory records the retirement date.
5. 12.5Discovery of undocumented APIs (traffic analysis, DNS and certificate records, cloud resource inventory, code search) MUST run at least monthly, and its results feed section 2.
6. 12.6Data flows to partners and third parties are documented per API and version, so a retirement or an incident shows who is affected.

Shaped by: Third-party developersRESTGraphQLgRPC

Data from a third-party API is input from outside the trust boundary, even when the vendor is trusted.

1. 13.1Before integrating a third-party API, the owner MUST complete vendor due diligence proportionate to the data shared (stricter where the integration involves personal data, payment data or secrets), and record the integration in the inventory.
2. 13.2Responses MUST be treated as untrusted: validated against an expected schema, size-limited, and sanitised or encoded before they are stored, rendered or used in queries.
3. 13.3Calls MUST use TLS with certificate validation enabled. Redirects from a third party MUST NOT be followed blindly; follow only to allowlisted hosts.
4. 13.4Calls MUST have timeouts, bounded retries and circuit breakers so a slow or failing provider does not exhaust our resources.
5. 13.5Credentials for third-party APIs MUST be stored in the secrets manager, scoped to the minimum, and rotated on the provider's schedule or on staff change, whichever is sooner.
6. 13.6Send the minimum data the provider needs. Integrations are reviewed when the provider changes ownership, terms or data location.

Shaped by: Consumes third-party APIs

Telemetry turns the controls above into something you can see working, and detects abuse that slips past them.

1. 14.1APIs MUST log: authentication successes and failures, authorisation denials, validation failures, rate-limit and quota events, administrative actions, sensitive flow events, and configuration changes. Each event carries timestamp, correlation ID, consumer ID, user ID (pseudonymous where possible), operation, object ID where relevant, source address and result.
2. 14.2Logs MUST NOT contain passwords, tokens, API keys, session identifiers, full card numbers or card verification codes; personal data is minimised or masked.
3. 14.3API logs MUST be sent to the central logging platform, protected from tampering and kept for at least 12 months, or longer where compliance confirms a tagged framework requires it.
4. 14.4Security operations MUST alert on: one consumer touching an unusual number of distinct object IDs or receiving many authorisation denials (possible BOLA probing); credential-stuffing and token-guessing patterns; spikes in errors or 429s; traffic to endpoints or hosts not in the inventory; and anomalies in sensitive flows.
5. 14.5Partner and third-party usage is reviewed per consumer each month for unusual volume, new scopes in use and access outside agreed hours or regions.
6. 14.6API incidents follow the incident response plan; API owners MUST be able to revoke a consumer's credentials and block a version within one hour.

Shaped by: Tier: HighPersonal data (PII)Payment card / account dataCredentials and secretsExternal consumers

Each control above is verified by at least one kind of test. Automated tests catch regressions; people catch logic flaws.

1. 15.1SAST, dependency (SCA) and secret scanning MUST run on every merge to an API repository. Critical and high findings block the merge or need an exception.
2. 15.2DAST MUST run authenticated, driven by the API specification, against a production-like environment on every release and at least weekly.
3. 15.3Specification-driven API fuzzing MUST run on every release of a public or partner API, including GraphQL depth, alias and batching cases and malformed and oversized protobuf messages.
4. 15.4Authorisation tests from section 5 (multi-user, multi-role, cross-tenant) MUST run in CI for every API.
5. 15.5Penetration testing by qualified testers, internal or external, at least every 12 months, and before any new public or partner API or major version goes live. Scope MUST cover the OWASP API Security Top 10 2023 and the sensitive business flows in section 9.
6. 15.6Findings are fixed within the deadlines in section 11 (7 days critical, 30 days high). Retests confirm the fix.
7. 15.7Testing only targets systems the organisation owns or is authorised to test.

Shaped by: Tier: HighGraphQLgRPC

Exceptions are allowed, temporary and visible.

1. 16.1An exception request MUST state: the clause, the API(s), the reason, the compensating controls, the residual risk rating, the API owner and an expiry date.
2. 16.2Exceptions expire after at most 3 months and are renewed only after a fresh review. Expired exceptions are reported to Chief Information Security Officer (CISO).
3. 16.3Approval: Application Security for low and medium residual risk; Chief Information Security Officer (CISO) for high residual risk or any API handling personal data, payment data or secrets.
4. 16.4No exception is granted for: accepting unsigned or "none"-algorithm tokens; disabling TLS certificate validation; unauthenticated access to personal data, payment data or secrets; or storing secrets in source code.
5. 16.5All exceptions are kept in one register that is reviewed at least quarterly.

Shaped by: Tier: HighPersonal data (PII)Payment card / account dataCredentials and secrets

A policy that is not reviewed drifts away from the APIs it governs.

1. 17.1Chief Information Security Officer (CISO) reviews this policy every 12 months, plus a mid-year check of metrics, and also after: a significant API security incident; a major architecture change (for example a new gateway or API style); a change to the regulatory context tags; or a new edition of the OWASP API Security Top 10.
2. 17.2The review uses these measures: share of APIs in the inventory with a named owner and a current specification; share of external APIs behind the gateway; shadow APIs found per discovery run; open findings past deadline; open and expired exceptions; and the date of the last penetration test per external API.
3. 17.3Changes are recorded in the version history with the date, the author and a summary, and communicated to API owners.

Shaped by: Tier: HighTag: PCI DSSTag: GDPRTag: PSD2Tag: SOC 2