Skip to main content
This reference is essential for your comprehensive understanding of Guardian and successful integration with our secure card data vault service. Guardian APIs make use of RESTful conventions when possible and where it makes sense. All calls use the standard HTTP verbs to express access semantics, like GET, POST, PATCH, and DELETE. Other related conventions for our API can be found in the section below.

​
JSON Conventions

  • Resources are addressable by a UUIDv4 id property.
  • Property names are always in snake_case.
  • Temporal data is encoded in ISO 8601 strings.

​
Empty Strings and Omitted Fields

The empty string is not a value. A string field is either omitted or present with a real value — and where a field is nullable, an explicit null unsets it. Never send "". Where a field is validated as a string, "" is rejected with 422 Unprocessable Entity and a field error on that path (see Request Errors for the response format). Not every field carries that validation, so do not treat the rejection as a safety net: where it is absent, "" is accepted and then stored or forwarded verbatim — an empty string travels further into a request than a missing field ever does.

​
Authentication

Guardian authenticates every request with an OAuth2 access token — a signed JWT — passed as a bearer token. Request the token with the client-credentials grant against the platform Authentication API; the token’s audience is your instance name, and its scopes gate the endpoints it may call.
Administrative endpoints use the same token carrying the relevant admin:* scope. See Authentication for the full scope reference.

​
API keys (deprecated)

Guardian still accepts a long-lived instance key in the x-api-key header, so existing integrations keep working. New integrations should use an access token instead.
The x-admin-token header it used to pair with has been replaced by scoped access tokens. Credentials must be handled with care and kept secure. Never hardcode tokens or API keys in your source code — keep them solely on your backend systems.

​
API Use

​
Instance URL

Guardian is provided as a service of the Hellgate Cloud Platform implementing the Composable Payment Architecture (CPA). Each instance is accessible at a unique host:
{instance} is your unique instance slug and eu1 is the current environment; both are provided during onboarding.

​
Pagination

Endpoints that return lists of objects support pagination. Guardian uses simple offset-based pagination with the following query parameters: Example request:
The response includes pagination metadata:

​
Request Errors

Guardian uses standard HTTP status codes to indicate client errors on the API level.
The response payload for processing errors follows a standard format.

​
Security Considerations

Guardian handles sensitive payment card data and requires strict security practices:
  • All communication must use HTTPS
  • Access tokens, and any remaining API keys, must be stored securely
  • PCI compliance requirements apply based on your integration approach
  • Session-based tokenization (SAQ-A+) is recommended over direct PAN handling (SAQ-D+)