Create inquiry

Guardian API (EAP)

Getting started

Guardian Early Access Program

Guardian in its CPA version is currently in early access. You can apply for access by contacting your account representative.

This reference is essential for your comprehensive understanding of Guardian CPA 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 CPA is provided as dedicated managed infrastructure. Each instance is accessible via a unique cluster identifier:

https://{cluster_id}.on-hellgate.cloud

Your cluster ID is provided during the onboarding process.

Idempotency

To prevent your system from handling requests twice and thus, for example, creating duplicate tokens, Guardian supports idempotency on requests to the API.

The behavior is controlled via the header field x-idempotency-key.

curl --header 'x-idempotency-key: <key>' ...

Endpoints that return lists of objects support pagination.

Guardian uses simple offset-based pagination with the following query parameters:

Parameter	Type	Description
`limit`	`integer`	The maximum amount of objects to be returned per request. Default is 50.
`after`	`string` (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+)

Download OpenAPI description

guardian-openapi.json

guardian-openapi.yaml

Overview

URL

https://hellgate.io/guardian

Starfish GmbH & Co. KG

hello@starfish.team

License

Hellgate API Terms

Servers

Managed instance of Guardian CPA

https://{cluster_id}.on-hellgate.cloud/

PCI Tokens

Management of card payment credentials under the ruling of PCI/DSS.

Operations

Network Tokens

Management of network tokens, including cryptograms for secure transactions.

Operations

Metadata Inquiries

Inquiries for card metadata based on PAN, PCI tokens, or network tokens.

Operations

Create inquiry

Request

Create a new inquiry for card metadata based on either a PAN, an existing PCI token, or a network token.

Security

APIKey or AdminToken

Headers

x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001

Bodyapplication/json

sourceobjectrequired

source.typestringrequired

Discriminator

source.account_numberstringrequired

source.cardholder_namestring

source.expiry_yearintegerrequired

source.expiry_monthintegerrequired

source.security_codestring

curl -i -X POST \
  https://my-cluster-id.on-hellgate.cloud/api/metadata/inquiries \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001' \
  -d '{
    "source": {
      "type": "pan",
      "account_number": "4111111111111111",
      "expiry_month": 12,
      "expiry_year": 2025,
      "security_code": "123"
    }
  }'

Responses

Success response

Bodyapplication/json

binstring[ 6 .. 8 ] charactersrequired

Example: "411111"

schemestringrequired

Enum"visa""mastercard""american express""discover""diners club""jcb""unionpay"

Example: "visa"

typestring

Enum"credit""debit""prepaid""other"

Example: "credit"

segmentstring

Enum"consumer""commercial"

Example: "consumer"

billing_currency_codestring= 3 characters

Example: "EUR"

issuer_namestring

Example: "Starfish Bank"

issuer_country_codestring

Example: "DE"

product_codestring

Example: "VISA-PLATINUM"

product_namestring

Example: "Visa Platinum Card"

Response

application/json

{
  "bin": "411111",
  "scheme": "visa",
  "type": "credit",
  "segment": "consumer",
  "billing_currency_code": "EUR",
  "issuer_name": "Starfish Bank",
  "issuer_country_code": "DE",
  "product_code": "VISA-PLATINUM",
  "product_name": "Visa Platinum Card"
}

Administration

Administrative operations for managing a Guardian instance, such as API keys.

Operations

Guardian API (EAP)

Getting started

JSON Conventions

Authentication

API Keys

Admin Tokens

API Use

Cluster-based Deployment

Idempotency

Pagination

Request Errors

Security Considerations

PCI Tokens

Network Tokens

Metadata Inquiries

Create inquiry

RequestExpand all

Responses

Was this helpful?

Administration

Request