X-API-Key: abc123

Key disimpan plaintext di database.
Key tidak punya owner.
Key tidak punya scope.
Key tidak punya expiry.
Key tidak bisa di-rotate tanpa downtime.
Key masuk access log.
Key dibagikan antar service.
Key dipakai sebagai user authentication.
Key berlaku lintas tenant.
Key bocor tapi tidak ada cara revoke cepat.

User credential    -> membuktikan manusia / subscriber / end-user
API key credential -> membuktikan aplikasi / client / integration

An API key authenticates the caller application, not the human user behind it.

login user
session user
mobile user authentication
SPA authentication
password reset
MFA bypass
privilege escalation

partner API integration
server-to-server call sederhana
internal automation
webhook sender identification
metered API access
low/medium risk machine client
legacy integration yang belum bisa OAuth2/mTLS

POST /payments/disbursements
POST /accounts/{id}/close
POST /identity/recovery/approve
POST /regulatory-cases/{id}/enforcement-actions

OAuth2 client credentials
mTLS
HMAC request signing
JWT client assertion
network allowlist
step-up approval
fine-grained authorization

API key = static bearer credential.
Siapa pun yang memegang key bisa memakainya.

blast radius = scope x lifetime x privilege x tenant reach x rate limit x observability gap

An API key will eventually leak.

Make leaked key detection fast, impact bounded, and replacement operationally safe.

Who is this client?

Can this client perform this action on this resource in this tenant?

User membuka UI.
Frontend menyimpan API key.
Frontend mengirim API key ke backend.
Backend menganggap API key sebagai user.

API key terekspos di browser.
Tidak ada user session lifecycle.
Tidak ada MFA.
Tidak ada device management.
Tidak ada account recovery lifecycle.
Tidak ada user consent.
Sulit revoke per device.
Sulit audit siapa manusia sebenarnya.

Do not put long-lived API keys in browser JavaScript, mobile public apps, or downloadable clients.

session cookie + backend
OIDC Authorization Code + PKCE + BFF
short-lived access token dengan refresh handled server-side

OAuth2/OIDC Authorization Code + PKCE
proof-of-possession bila memungkinkan
server-side risk checks

abc123
partnerA-secret
tenant-42-key
000000001

ak_live_2YJ7M5W6Q9ZC3D4E5F6G7H8J9K0L1P2R3S4T5V6W7X8Y9Z0A

ak         -> product/type prefix
live       -> environment marker, optional
2YJ7...    -> high entropy random secret

ak_live_kid_7GHT3M.secret_c3Pj9VxX7rZfK2nQm9...

<public_prefix>_<key_id>.<secret>

ak_live_01HY7Q6MS5RVA4CNZ2Y9Q82F3K.1sM7xOzZP6EwWkz0w8v2f5rAq...

1. Parse key_id.
2. Load metadata by key_id.
3. Hash/HMAC secret input.
4. Compare dengan stored hash menggunakan constant-time comparison.

Do not derive API keys from username, tenant id, email, timestamp, sequence, or UUID alone.

Generate at least 128 bits of entropy for normal API keys.
Use 256 bits for high-value credentials.
Use SecureRandom.
Encode using Base64URL without padding or Crockford Base32.

import java.security.SecureRandom;
import java.util.Base64;

public final class ApiKeyGenerator {
    private static final SecureRandom RNG = new SecureRandom();

    public static String generateSecret256() {
        byte[] bytes = new byte[32]; // 256 bits
        RNG.nextBytes(bytes);
        return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
    }
}

UUIDv4 has about 122 random bits.
It may be acceptable for identifiers, but API key secret design usually benefits from explicit byte-length generation and encoding control.

api_key_value text not null

secret_hash bytea not null

Password -> slow password hashing: Argon2id / bcrypt / PBKDF2
API key  -> HMAC/SHA-256 or keyed hash over high-entropy random secret is usually appropriate

stored_secret_hash = HMAC-SHA-256(server_pepper, raw_secret)

If database leaks alone, attacker cannot verify guessed keys without pepper.
If keys are high entropy, offline guessing is infeasible.
HMAC gives fixed-size indexed/compared representation.
Pepper lives outside database, preferably in KMS/Vault/secret manager.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public final class ApiKeyHasher {
    private final byte[] pepper;

    public ApiKeyHasher(byte[] pepper) {
        this.pepper = pepper.clone();
    }

    public byte[] hash(String rawSecret) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(pepper, "HmacSHA256"));
            return mac.doFinal(rawSecret.getBytes(StandardCharsets.UTF_8));
        } catch (Exception e) {
            throw new IllegalStateException("Cannot hash API key", e);
        }
    }
}

import java.security.MessageDigest;

boolean matches(byte[] expected, byte[] actual) {
    return MessageDigest.isEqual(expected, actual);
}

Arrays.equals(expected, actual) // may short-circuit
expectedString.equals(actualString)

create table api_client (
    id uuid primary key,
    tenant_id uuid not null,
    client_code text not null,
    display_name text not null,
    owner_team text,
    contact_email text,
    status text not null check (status in ('active', 'disabled')),
    created_at timestamptz not null default now(),
    disabled_at timestamptz,
    unique (tenant_id, client_code)
);

create table api_key (
    id uuid primary key,
    client_id uuid not null references api_client(id),
    key_id text not null unique,
    prefix text not null,
    secret_hash bytea not null,
    status text not null check (status in ('active', 'pending', 'deprecated', 'revoked', 'expired')),
    environment text not null check (environment in ('test', 'live')),
    created_at timestamptz not null default now(),
    activated_at timestamptz,
    expires_at timestamptz,
    last_used_at timestamptz,
    revoked_at timestamptz,
    revoked_reason text,
    replaced_by_api_key_id uuid references api_key(id),
    version bigint not null default 0
);

create table api_client_scope (
    client_id uuid not null references api_client(id),
    scope text not null,
    primary key (client_id, scope)
);

create index idx_api_key_client_status on api_key(client_id, status);
create index idx_api_key_expires_at on api_key(expires_at);

raw secret
full key in audit event
full key in last used metadata

prefix: ak_live_01HY7Q6MS5...
suffix: optional last 4 chars for UI display, not for lookup

Only active keys should be accepted by default.
Deprecated acceptance must be explicit and time-bounded.

extract -> parse -> lookup -> status -> expiry -> verify -> scope -> rate limit -> principal

public ApiClientPrincipal authenticate(ApiKeyCredential credential) {
    ParsedApiKey parsed = parser.parse(credential.rawValue());

    ApiKeyRecord record = repository.findByKeyId(parsed.keyId())
        .orElseThrow(BadApiKeyException::new);

    if (!record.isActive(clock.instant())) {
        throw new BadApiKeyException();
    }

    byte[] actualHash = hasher.hash(parsed.secret());
    if (!constantTimeEquals(record.secretHash(), actualHash)) {
        throw new BadApiKeyException();
    }

    ApiClient client = clientRepository.findActive(record.clientId())
        .orElseThrow(BadApiKeyException::new);

    quotaLimiter.check(client.id(), credential.sourceIp());

    repository.touchLastUsedAsync(record.id(), clock.instant());

    return new ApiClientPrincipal(
        client.id(),
        client.tenantId(),
        client.clientCode(),
        client.scopes(),
        record.id()
    );
}

{ "error": "API key exists but expired" }

{ "error": "invalid_client" }

{
  "event": "api_key_auth_failed",
  "reason": "expired",
  "key_id": "01HY7Q6MS5RVA4CNZ2Y9Q82F3K",
  "tenant_id": "...",
  "source_ip": "203.0.113.10"
}

Authorization: ApiKey ak_live_01HY...secret...

X-API-Key: ak_live_01HY...secret...

GET /resource?api_key=ak_live_...

browser history
server logs
reverse proxy logs
referrer headers
monitoring tools
analytics
screenshots

TLS
Authorization header
no query string credentials
redacted logs
shorter expiry
rotation policy
optional HMAC/mTLS

ApiKeyAuthenticationToken
ApiKeyAuthenticationConverter
ApiKeyAuthenticationProvider
AuthenticationFilter
SecurityFilterChain

import org.springframework.security.authentication.AbstractAuthenticationToken;
import org.springframework.security.core.GrantedAuthority;

import java.util.Collection;

public final class ApiKeyAuthenticationToken extends AbstractAuthenticationToken {
    private final Object principal;
    private final String apiKey;

    private ApiKeyAuthenticationToken(
            Object principal,
            String apiKey,
            Collection<? extends GrantedAuthority> authorities,
            boolean authenticated
    ) {
        super(authorities);
        this.principal = principal;
        this.apiKey = apiKey;
        setAuthenticated(authenticated);
    }

    public static ApiKeyAuthenticationToken unauthenticated(String rawApiKey) {
        return new ApiKeyAuthenticationToken(null, rawApiKey, null, false);
    }

    public static ApiKeyAuthenticationToken authenticated(
            ApiClientPrincipal principal,
            Collection<? extends GrantedAuthority> authorities
    ) {
        return new ApiKeyAuthenticationToken(principal, null, authorities, true);
    }

    @Override
    public Object getCredentials() {
        return apiKey;
    }

    @Override
    public Object getPrincipal() {
        return principal;
    }

    @Override
    public void eraseCredentials() {
        super.eraseCredentials();
        // raw key is held in final field in this simplified example.
        // In production, use a mutable credential holder or ensure the token is short-lived.
    }
}

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.security.core.Authentication;
import org.springframework.security.web.authentication.AuthenticationConverter;

public final class ApiKeyAuthenticationConverter implements AuthenticationConverter {
    @Override
    public Authentication convert(HttpServletRequest request) {
        String authorization = request.getHeader("Authorization");
        if (authorization != null && authorization.startsWith("ApiKey ")) {
            return ApiKeyAuthenticationToken.unauthenticated(authorization.substring("ApiKey ".length()).trim());
        }

        String xApiKey = request.getHeader("X-API-Key");
        if (xApiKey != null && !xApiKey.isBlank()) {
            return ApiKeyAuthenticationToken.unauthenticated(xApiKey.trim());
        }

        return null;
    }
}

import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;

public final class ApiKeyAuthenticationProvider implements AuthenticationProvider {
    private final ApiKeyAuthenticator authenticator;

    public ApiKeyAuthenticationProvider(ApiKeyAuthenticator authenticator) {
        this.authenticator = authenticator;
    }

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        String rawKey = (String) authentication.getCredentials();
        ApiClientPrincipal principal = authenticator.authenticate(rawKey);
        return ApiKeyAuthenticationToken.authenticated(principal, principal.authorities());
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return ApiKeyAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

import org.springframework.context.annotation.Bean;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.AuthenticationFilter;

@Bean
SecurityFilterChain apiSecurity(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
    AuthenticationFilter apiKeyFilter = new AuthenticationFilter(
        authenticationManager,
        new ApiKeyAuthenticationConverter()
    );
    apiKeyFilter.setSuccessHandler((request, response, authentication) -> {
        // Continue filter chain. AuthenticationFilter success behavior may need customization depending on setup.
    });

    http
        .securityMatcher("/api/**")
        .csrf(csrf -> csrf.disable())
        .addFilter(apiKeyFilter)
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/api/public/**").permitAll()
            .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
            .anyRequest().authenticated()
        );

    return http.build();
}

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

public final class ApiKeyFilter extends OncePerRequestFilter {
    private final ApiKeyAuthenticator authenticator;

    public ApiKeyFilter(ApiKeyAuthenticator authenticator) {
        this.authenticator = authenticator;
    }

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        try {
            String rawKey = extractApiKey(request);
            if (rawKey != null) {
                ApiClientPrincipal principal = authenticator.authenticate(rawKey);
                ApiKeyAuthenticationToken auth = ApiKeyAuthenticationToken.authenticated(
                    principal,
                    principal.authorities()
                );
                SecurityContextHolder.getContext().setAuthentication(auth);
            }

            filterChain.doFilter(request, response);
        } catch (BadApiKeyException ex) {
            SecurityContextHolder.clearContext();
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json");
            response.getWriter().write("{\"error\":\"invalid_client\"}");
        } finally {
            // Usually Spring Security context persistence clears the context.
            // Keep this here only if this filter is used outside the managed security chain.
        }
    }

    private String extractApiKey(HttpServletRequest request) {
        String auth = request.getHeader("Authorization");
        if (auth != null && auth.startsWith("ApiKey ")) {
            return auth.substring(7).trim();
        }
        String key = request.getHeader("X-API-Key");
        return key == null || key.isBlank() ? null : key.trim();
    }
}

AuthenticationProvider model -> cleaner integration with Spring Security
OncePerRequestFilter -> simpler, but easier to bypass/misorder if careless

import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;
import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.container.ContainerRequestFilter;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.SecurityContext;
import jakarta.ws.rs.ext.Provider;

import java.io.IOException;
import java.security.Principal;

@Provider
@Priority(Priorities.AUTHENTICATION)
public final class ApiKeyRequestFilter implements ContainerRequestFilter {
    private final ApiKeyAuthenticator authenticator;

    public ApiKeyRequestFilter(ApiKeyAuthenticator authenticator) {
        this.authenticator = authenticator;
    }

    @Override
    public void filter(ContainerRequestContext ctx) throws IOException {
        String rawKey = extract(ctx);
        if (rawKey == null) {
            return;
        }

        try {
            ApiClientPrincipal principal = authenticator.authenticate(rawKey);
            SecurityContext original = ctx.getSecurityContext();
            ctx.setSecurityContext(new ApiKeySecurityContext(principal, original.isSecure()));
        } catch (BadApiKeyException ex) {
            ctx.abortWith(Response.status(Response.Status.UNAUTHORIZED)
                .entity("{\"error\":\"invalid_client\"}")
                .type("application/json")
                .build());
        }
    }

    private String extract(ContainerRequestContext ctx) {
        String auth = ctx.getHeaderString(HttpHeaders.AUTHORIZATION);
        if (auth != null && auth.startsWith("ApiKey ")) {
            return auth.substring("ApiKey ".length()).trim();
        }
        return ctx.getHeaderString("X-API-Key");
    }
}

import jakarta.ws.rs.core.SecurityContext;
import java.security.Principal;

public final class ApiKeySecurityContext implements SecurityContext {
    private final ApiClientPrincipal principal;
    private final boolean secure;

    public ApiKeySecurityContext(ApiClientPrincipal principal, boolean secure) {
        this.principal = principal;
        this.secure = secure;
    }

    @Override
    public Principal getUserPrincipal() {
        return principal;
    }

    @Override
    public boolean isUserInRole(String role) {
        return principal.scopes().contains(role) || principal.authorities().stream()
            .anyMatch(a -> a.getAuthority().equals(role));
    }

    @Override
    public boolean isSecure() {
        return secure;
    }

    @Override
    public String getAuthenticationScheme() {
        return "ApiKey";
    }
}

partner_api_key -> can do everything

orders:read
orders:create
orders:cancel
quotes:read
quotes:create
webhooks:send
cases:read
cases:update-status

<resource>:<action>

quote:read
quote:create
order:submit
order:cancel
case:read
case:transition
payment:initiate
payment:refund

admin
full_access
partner
standard
api

scope + tenant + resource owner + amount limit + workflow state + approval status

public void requireScope(ApiClientPrincipal client, String requiredScope) {
    if (!client.scopes().contains(requiredScope)) {
        throw new ForbiddenException("insufficient_scope");
    }
}

public void authorizeOrderSubmit(ApiClientPrincipal client, Order order) {
    requireScope(client, "order:submit");

    if (!order.tenantId().equals(client.tenantId())) {
        throw new ForbiddenException("cross_tenant_access_denied");
    }

    if (!order.partnerId().equals(client.clientId())) {
        throw new ForbiddenException("resource_owner_mismatch");
    }

    if (!order.isSubmittable()) {
        throw new ConflictException("order_not_submittable");
    }
}

api_key -> client_id
client_id -> many tenants
request has tenant_id param

api_key -> client_id -> tenant_id

create table api_client_tenant_grant (
    client_id uuid not null references api_client(id),
    tenant_id uuid not null,
    grant_status text not null,
    created_at timestamptz not null default now(),
    primary key (client_id, tenant_id)
);

request tenant -> client tenant grant -> resource tenant -> authorization policy

Never infer tenant solely from request input when credential metadata already has tenant context.

api_key_id
client_id
tenant_id
source_ip
endpoint group
scope
risk class

public final class ApiQuotaLimiter {
    private final RedisClient redis;

    public void check(String clientId, String routeGroup) {
        String key = "quota:" + routeGroup + ":" + clientId + ":" + currentMinute();
        long count = redis.incr(key);
        if (count == 1) {
            redis.expire(key, 90);
        }
        if (count > limitFor(routeGroup)) {
            throw new TooManyRequestsException();
        }
    }
}

Rate limit authenticated clients by client id.
Rate limit invalid requests by IP/subnet/fingerprint.
Do not let unknown API key attempts hit database at unlimited rate.
Cache negative lookup carefully with short TTL.

Allow overlapping active keys.
Show secret once.
Expose last_used_at per key.
Allow revocation per key.
Do not revoke all keys accidentally unless incident mode.
Support automation through secure admin API.

old key -> replaced_by_api_key_id -> new key

name
prefix
created_at
last_used_at
expires_at
status
scopes
environment
created_by
revoked_by

test keys: 30-90 days
live partner keys: 90-365 days depending on risk
high-risk keys: 30-90 days + HMAC/mTLS
internal automation keys: prefer workload identity/mTLS; if not, 90 days

expiry warning at T-30/T-14/T-7/T-1
owner contact
dashboard
last_used_at
automated rotation option
emergency extension workflow

A key expiry policy is only mature if key owners can rotate before expiry without opening a ticket under pressure.

Database status check on every request -> simple, slower
Cache key metadata with short TTL -> faster, revocation delayed by TTL
Event-driven cache invalidation -> fast, more complex
Redis active key cache -> fast but needs authoritative DB fallback

DB is source of truth.
App caches active key metadata for 30-120 seconds.
Revocation publishes invalidation event.
High-risk endpoints bypass cache or require fresh check.

{
  "event_type": "api_key.revoked",
  "api_key_id": "...",
  "client_id": "...",
  "tenant_id": "...",
  "reason": "suspected_leak",
  "revoked_by": "security-ops",
  "occurred_at": "2026-07-03T04:00:00Z"
}

Delete removes auditability.
Revoke preserves evidence.

Authorization header
X-API-Key header
query string
exception message
request dump
access logs
proxy logs
APM spans
debug logs
failed auth logs
webhook delivery logs

{
  "event": "api_request_authenticated",
  "auth_type": "api_key",
  "key_id": "01HY7Q6MS5RVA4CNZ2Y9Q82F3K",
  "key_prefix": "ak_live_01HY7Q6M",
  "client_id": "...",
  "tenant_id": "...",
  "route": "POST /orders",
  "source_ip": "203.0.113.10"
}

{
  "headers": {
    "X-API-Key": "ak_live_01HY...raw-secret..."
  }
}

public final class HeaderRedactor {
    private static final Set<String> SECRET_HEADERS = Set.of(
        "authorization",
        "x-api-key",
        "x-signature",
        "cookie",
        "set-cookie"
    );

    public static String safeHeader(String name, String value) {
        if (SECRET_HEADERS.contains(name.toLowerCase(Locale.ROOT))) {
            return "[REDACTED]";
        }
        return value;
    }
}

api_key.auth.success.count
api_key.auth.failure.count by reason
api_key.auth.latency
api_key.lookup.latency
api_key.cache.hit.rate
api_key.revoked.used.count
api_key.expired.used.count
api_key.rotation.age.days
api_key.last_used.age.days
api_key.quota.rejected.count

same key from new ASN/country
same key from many IPs in short window
revoked key still being used
expired key still being used
key used after long dormancy
key using new endpoint/scope
failure spike for unknown key ids
prefix enumeration attempts
sudden quota spike

IF api_key_id is active
AND source_asn not in historical_asn_set
AND endpoint risk >= high
THEN alert security_ops with severity medium/high

create client
create key
show secret once
list keys
show last used
show scopes
add/remove scopes
rotate key
revoke key
disable client
export audit events
configure quota
set owner contact

Only privileged admins can create/revoke keys.
Key creation requires reason and owner.
High-risk scopes require approval.
Raw secret is displayed once.
Raw secret is never emailed.
Admin actions are audited.

Developer asks in Slack.
Ops creates key manually in database.
Ops sends key via chat.
No owner, no expiry, no scopes.

Self-service request -> approval -> generated key -> displayed once -> owner stored -> expiry warnings -> audit trail

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuthorization:
      type: http
      scheme: ApiKey

where to send key
that HTTPS is required
that query string is forbidden
error format
rate limit headers
rotation expectations
scope model

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "invalid_client"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "insufficient_scope"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limited"
}

unknown key id
wrong secret
expired key
revoked key
client disabled
scope missing for a sensitive endpoint

Every request hits PostgreSQL.

Cache key metadata by key_id.
Cache only active/deprecated metadata.
Use short TTL.
Invalidate on revoke/disable/scope change.
Never cache raw key.

public record CachedApiKey(
    UUID apiKeyId,
    UUID clientId,
    UUID tenantId,
    String keyId,
    byte[] secretHash,
    Set<String> scopes,
    Instant expiresAt,
    String status,
    long version
) {}

If secret_hash is in cache, compromise of app memory/cache can aid abuse.

protect cache network
encrypt in transit
short TTL
least privilege access
cache segmentation
avoid exposing cache dump
clear on incident

key_id not found -> cache miss result for 10-30 seconds

If you create a new key with same id impossible due randomness.
If parser accepts short user-controlled id, attacker can poison many cache entries.

strict key format
length limit
rate limit before database
small TTL
bounded cache size

1. Identify key id/prefix from leaked material.
2. Revoke key immediately.
3. Identify client, tenant, scopes, and owner.
4. Pull last_used_at and recent request logs.
5. Detect unusual IP/ASN/endpoint/resource access.
6. Rotate replacement key if client still legitimate.
7. Notify owner/partner.
8. Review data access and mutations.
9. Revoke related keys if sharing suspected.
10. Create post-incident control improvement.

select *
from api_key
where key_id = :key_id;

select route, source_ip, count(*), min(occurred_at), max(occurred_at)
from api_key_event
where api_key_id = :api_key_id
  and occurred_at > now() - interval '30 days'
group by route, source_ip
order by count(*) desc;

Was the key used after leak time?
Was it used from abnormal IPs?
Was it used against high-risk endpoints?
Did it access cross-tenant resources?
Were mutations performed?
Could logs contain the raw key elsewhere?
Are downstream systems caching this credential?

caller is a confidential server-side client
risk is low to medium
integration needs simplicity
credential can be stored securely
scopes and revocation are implemented
TLS is mandatory

caller is browser/mobile public client
operation is high financial/regulatory risk
request integrity matters
replay must be prevented
non-repudiation-like evidence is needed
client identity needs certificate-grade assurance

[ ] SecureRandom with >=128-bit entropy
[ ] environment-aware prefix
[ ] key id separated from secret
[ ] raw secret displayed once
[ ] secret hash stored, not raw secret
[ ] owner/contact captured
[ ] tenant binding captured
[ ] scopes assigned explicitly
[ ] expiry set
[ ] audit event emitted

[ ] HTTPS only
[ ] no query string credentials
[ ] strict parser
[ ] lookup by key id/prefix
[ ] constant-time secret comparison
[ ] active/expired/revoked status checked
[ ] tenant-bound principal created
[ ] scope-based authorization enforced
[ ] rate limiting enforced
[ ] safe generic errors

[ ] rotation supported
[ ] revocation supported
[ ] last_used_at tracked
[ ] suspicious usage detection
[ ] log redaction
[ ] secret scanning
[ ] expiry notification
[ ] emergency revoke runbook
[ ] cache invalidation tested

read quotes
create quotes
submit orders
receive webhooks
not access other tenants
not call payment endpoints
rotate without downtime

1. API client schema
2. API key schema
3. key format
4. validation pipeline
5. scope list
6. rate limit policy
7. revocation runbook
8. OpenAPI security scheme
9. test matrix

What happens if the key is expired?
What happens if tenant id in URL differs from key tenant?
What happens if revoked key is used from known IP?
What happens if key id exists but secret mismatches?
What happens if partner needs emergency rotation?
What happens if API gateway logs the Authorization header?

API key = high-entropy client credential + owner + tenant + scope + expiry + revocation + rotation + observability

static string in config table

Every API key must have bounded privilege, bounded lifetime, known ownership, safe storage, and a tested death path.