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.
  • Guardian does not support empty strings. To unset a string value, use an explicit null value instead.
  • Temporal data is encoded in ISO 8601 strings.

​
Authentication

Guardian supports two types of authentication to accommodate different access patterns and security requirements.

​
API Keys

Standard API keys are used for most Guardian operations and are passed via the HTTP header x-api-key. 
curl --header 'x-api-key: <SECRET>' \
  --request POST 'https://my-cluster-id.on-hellgate.cloud/api/...'

​
Admin Tokens

Admin tokens provide elevated privileges for administrative operations such as API key management. They are passed via the HTTP header x-admin-token. 
curl --header 'x-admin-token: <ADMIN_SECRET>' \
  --request POST 'https://my-cluster-id.on-hellgate.cloud/api/admin/...'
Both authentication methods must be handled with care and kept secure. Never hardcode the API keys or admin tokens in your source code, but keep them solely on your backend systems.

​
API Use

​
Cluster-based Deployment

Guardian is provided as a service of the Hellgate Cloud Platform implementing Composable Payment Architecture. Each instance is accessible via a unique cluster identifier: 
https://{cluster_id}.on-hellgate.cloud
Your cluster ID is provided during the onboarding process.

​
Pagination

Endpoints that return lists of objects support pagination. Guardian uses simple offset-based pagination with the following query parameters:
ParameterTypeDescription
limitintegerThe maximum amount of objects to be returned per request. Default is 50.
afterstring (uuid)The id of the element from which on-wards the new list is determined. It is typically the last element from the previous list.
Example request: 
curl --header 'x-api-key: <SECRET>' \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens?limit=25&after=08f4b968-259a-4989-b5ab-09ef9414f983'
The response includes pagination metadata: 
{
  "data": [...],
  "links": {
    "next": "https://my-cluster-id.on-hellgate.cloud/api/pci/tokens?limit=25&after=605d229d-fc8a-4017-b115-2e606031bd79",
  }
}

​
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.
{
"status": "the HTTP status code",
"classifier": "the classifier of the error",
"message": "interesting for humans..."
}

​
Security Considerations

Guardian handles sensitive payment card data and requires strict security practices:
  • All communication must use HTTPS
  • API keys and admin tokens 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+)