Maintenance
Forward Header Overrides and PCI Token Expiry in the Specification
The OpenAPI document now declares thex-own-header-name / x-own-header-value
header pair on all three forward operations — card data, cryptogram, and wallet
token. Guardian strips the credential your call authenticates with before
forwarding; the pair sets the destination’s own credential on the forwarded
request. The behavior is unchanged and was already described in the
PCI Tokens guide; clients
generated from the document alone could not send a destination credential
before.pci_token.expires_at is now typed nullable: a token created without an expiry
returns "expires_at": null, which a schema-validating client previously had
to reject.Documentation only; no endpoint changed. Regenerate clients.Improvement
Data Classification Markers on Card Fields
The Guardian API reference now marks every field that carries regulated data.account_number and the PAN returned on a cryptogram are marked pci-pan;
security_code, the cryptogram itself, and the dynamic CVV are marked
pci-sad; cardholder_name is marked pii.The marker is a gate as well as a label: sending values into pci-pan or
pci-sad fields requires your PCI DSS certification on file at SAQ-D or a full
Report on Compliance. This is what makes the difference between the
session-based and direct-PAN integration paths visible field by field.Fields without a marker hold none of those categories — masked and truncated
card numbers are the common example. The
full legend
is on the API reference.Nothing about any endpoint changed — this is documentation only.Maintenance
Polymorphic Request Bodies Specified as Discriminated Unions
The request bodies that accept several shapes —source on PCI token creation,
network token creation, and metadata inquiry, plus the cryptogram request — are
now specified as discriminated unions on type. The accepted requests are
unchanged; what changes is that the specification states which type selects
which shape, so the reference documentation shows one tab per source and
generated clients get a proper tagged union.Three places where the specification was looser than the API and has been
corrected: type is required on the cryptogram request, and both type and
account_number are required on a metadata inquiry from a PAN. Requests
missing them were already rejected — the document simply did not say so.Responses that vary by shape rather than by a tag — PCI token creation, network
token creation, and the cryptogram response — keep their existing structure and
now document how to tell the variants apart.Improvement
Richer Network Token Provisioning Events
network_token.provisioned events now carry the network_token_id, the
pci_token_id, and the card’s last_four, so you can reconcile provisioning
activity against your token records without extra lookups.Improvements and bugfixes
- Fixed access token verification: a valid OAuth2 access token could be
rejected with
401 invalid_token. See Authentication.
ChangedDeprecation
OAuth2 Access Tokens Replace API Keys
Guardian now authenticates with an OAuth2 access token, the same client-credentials flow used across the Hellgate Cloud Platform. Request a token from the Authentication API with your instance name as the audience, and send it asAuthorization: Bearer <access_token>. The scopes that previously sat on an
API key now travel in the token.Long-lived x-api-key credentials are deprecated. Existing integrations
keep working, but new ones should use access tokens. The x-admin-token
header has been replaced — administrative endpoints now accept the same
access token carrying the relevant admin:* scope. See
Authentication.New Release
Card Fingerprints on PCI Tokens
PCI token responses can now includecard.fingerprint: a deterministic,
non-reversible identifier of the card number, unique per Guardian instance.
The same card always produces the same fingerprint — across session and
pan tokenization and after a reissue with a new expiry date — so you can
recognize a returning card without handling the PAN. The field is read-only
and enabled per instance. See
PCI Tokens for
details.Changed
Simpler Apple Pay Domain Verification on Self-Managed Deployments
Onself_managed deployments, registering an Apple Pay domain now marks it
verified immediately: you attest domain ownership to Apple yourself by
registering the domain in the Apple Developer portal, where Apple fetches the
domain-association file you serve. Guardian no longer calls Apple during
registration on these deployments; only sf_operated deployments verify
domains against Apple’s Web Merchant Registration API in the background. See
Apple Pay
for the updated flow.New Release
Apple Pay Operating Modes and Settings
Guardian Apple Pay deployments now run in one of two modes. Inself_managed
mode (the default) you upload your own Apple identity and manage the
certificates yourself; in sf_operated mode Starfish operates the Apple
Developer relationship and mounts the identity and certificates for you, so
the settings-upload and certificate-management endpoints are disabled and
return 409 with the classifier APPLE_PAY_CERT_MANAGEMENT_UNAVAILABLE.Self-managed operators upload their Apple identity up front with the new
Update settings
endpoint (merchant_identifier, display_name, domain_association_content,
and csr_common_name), which Guardian reads when generating CSRs, serving the
domain-association file, and validating merchant sessions. See
Apple Pay for the full
setup.New Release
Wallet Tokens with Apple Pay
Guardian now accepts Apple Pay payments as wallet tokens. Pass the encryptedPKPaymentToken payload straight to Guardian, and it verifies the EC_v1
signature against Apple’s trusted certificates, decrypts, and stores the
device token server-side, so the decrypted card data never touches your
systems. Guardian also proxies Apple Pay merchant-session validation, so the
browser’s onvalidatemerchant exchange completes without you holding any
Apple certificates. From there you can forward the resulting
wallet token to your PSP
or acquirer. See Apple Pay
to get started.New Release
Apple Pay Certificate and Domain Management
Guardian now manages the credentials Apple Pay needs: it generates payment processing and merchant identity CSRs with the private keys held inside its PCI boundary, accepts the certificates Apple signs, tracks their lifecycle (pending, active, retired, disabled) with per-certificate audit
events, and registers and verifies the merchant domains that present the
Apple Pay button. See
Apple Pay
for the setup steps.New Release
Wallet Tokens with Google Pay
Guardian now accepts device wallet payments, starting with Google Pay. Pass the encrypted Google Pay payload straight to Guardian — it verifies the ECv2 signature chain, decrypts, and stores the credential server-side, so the decrypted card data never touches your systems. From there you can forward the resulting wallet token to your PSP or acquirer, and promote a card-on-file (PAN_ONLY) token to a full network
token. See Google Pay
to get started.New ReleaseImprovement
JWT Authentication
A new JWT authentication lane runs in parallel to API keys. Guardian validates incoming tokens against your JWKS endpoint, letting you authenticate services with short-lived JWTs instead of, or alongside, long-lived API keys.Network Token Cryptogram Forwarding
You can now forward a network token cryptogram by reference onPOST /api/network/tokens/{id}/forward, so Guardian resolves the cryptogram
server-side and it never touches your systems. Forward templates also expose
more binds — including dynamic_cvv and additional network token fields — for
richer downstream requests.Token Lifecycle Controls
New token lifecycle controls let you set and manage expiration on stored tokens. Guardian accepts anexpiration_time alias for expires_in, and a
session’s expires_in now consistently takes precedence over the ephemeral
payload flag.Improvements and bugfixes
- Guardian now detects PANs in non-PAN attributes, catching card data that would otherwise slip through in the wrong field.
- Ingress forwarding headers are no longer relayed to destinations, keeping internal routing headers out of your outbound proxy requests.
- Network token create responses now serialize
pci_token_id. - Clearer proxy template errors: Guardian returns
422when a placeholder resolves to a map, validates unwrap placeholders inside multi-part templates, and gives more precise messages for non-renderable placeholders. - Ephemeral sessions without an
expires_inare handled correctly.
New ReleaseImprovement
Guardian Admin UI
Guardian now ships with a built-in Admin UI for day-to-day token operations. Browse and manage tokens, handle API keys with proper timezone-aware expiration, and walk new operators through token creation — all backed by a Playwright end-to-end test suite so it stays solid release after release.Metadata Inquiry Endpoint
A newPOST /metadata/inquiry endpoint lets you look up issuer metadata
on-demand. The endpoint is feature-flagged per tier, propagates the
x-request-id end-to-end as a correlation ID, and emits a billing event
tagged with the requester’s contract ID — so reporting and chargeback
reconciliation work out of the box.Improvements and bugfixes
- American Express now renders with its proper scheme name in admin views.
- Metadata inquiry events include
network_token_idfor richer reconciliation data. - Hellgate SDK
<script>tag no longer carries SRI/crossoriginattributes, simplifying embedding.
New ReleaseImprovement
Token Import
Migrating into Guardian from a legacy vault just got dramatically easier. A new admin Tokens Import workflow lets you bulk-load tokens via SFTP, with vault key handling that accepts both PEM and OpenSSH key formats. Move large token estates in hours, not weeks.Improvements and bugfixes
- Vault error handling is now much more informative — fewer mystery failures, more actionable messages.
- Clearer error response when creating a PCI token with invalid input.
New ReleaseImprovement
Generic Token Types API
Building on January’s Generic Tokens launch, you can now manage token type definitions through a new admin API:GET /api/admin/types,
GET /api/admin/types/{id}, and DELETE /api/admin/types/{id}. Type
schemas are validated at token-creation time, and you can filter your
generic tokens by type_id — making it straightforward to organize
SEPA credentials separately from API keys, for example.Improvements and bugfixes
- PCI token limits are now checked before network tokenization, avoiding half-completed states when a tenant hits its cap.
- Network token status is validated before cryptogram creation, surfacing a clean error instead of an opaque failure deep in the cryptogram path.
- Token requestor returns proper user-facing error messages.
404response shape is now consistent across the API.- Completed sessions return a sensible response even when the network token attempt failed.
- Added PAYONE test cards to the test fixtures.
New ReleaseMaintenance
Introduction of Generic Tokens
Effecitve with this release, you can now store arbitrary payloads (for example SEPA credentials, API keys, or other sensitive data). Find more information in our documentation.Improved TMS Support
The integration of VISA Token Management Service (TMS) was update for better feature coverage and more flexibility.New ReleaseMaintenance
Added support for VISA Token Management Service (TMS)
Effecitve with this release another backend for network token management was added. This brings more options and better flexibility.Bugfixes
- Allow deletion of network tokens in case of active cryptograms.
- Better handling of image dimensions of card-art data.
- Better error messages for missing data in scheme cryptograms.
ImprovementMaintenance
New Release