Skip to content
PCI Tokens
/
Foward card data

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>' ...

Pagination

Endpoints that return lists of objects support pagination.

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

Parameter Type Description
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+)
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

Languages
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

Create token

Request

Create a new token in the PCI/DSS scope. This type of token protects sensitive card payment credentials.

There are two ways to create the token, which depend on the level of your PCI/DSS compliance:

Source ComplianceDescription
sessionMin. SAQ-A+This is the most common way to create a token. It will leverage the SDKs of Guardian to securely capture the cardholder data and send it encrypted to the API.
panMin. SAQ-D+In case you have the required compliance to handle cardholder data yourself, you can also just import the full data in exchange for a token.
Security
APIKey or AdminToken
Headers
x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001
Bodyapplication/json
expiration_timeinteger[ 1 .. 2592000 ]

The expiry time is used to specify after how many seconds a token should be automatically deleted after creation.

metadataobject

Key-value pairs (max 20) with max 100 chars each pair.

sourceanyrequired
Default "session"
source.​typestringrequired
Discriminator
curl -i -X POST \
  https://my-cluster-id.on-hellgate.cloud/api/pci/tokens \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001' \
  -d '{
    "source": {
      "type": "session"
    }
  }'

Responses

Success response

Bodyapplication/json
One of:
session_idstring(uuid)required
Response
application/json
{
  "session_id": "8744c9ea-a02b-4ae6-875c-b64fc333e3ef"
}

Get tokens

Request

List all tokens in the PCI/DSS scope.

Security
APIKey or AdminToken
Query
afterstring(uuid)

The ID of the token after which to start listing. This is used for pagination.

limitinteger[ 1 .. 100 ]
Default 20
curl -i -X GET \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens?after=497f6eca-6276-4993-bfeb-53cbbbba6f08&limit=20' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
dataArray of itemsrequired
Example: [{"id":"8744c9ea-a02b-4ae6-875c-b64fc333e3ef","card":{"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"},"created_at":"2023-10-01T12:00:00Z"}]
data[].​[0]object
Example: {"id":"8744c9ea-a02b-4ae6-875c-b64fc333e3ef","card":{"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"},"created_at":"2023-10-01T12:00:00Z"}
linksobjectrequired
Example: {"next":"https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20"}
links.​nextstring(uri)required
Example: "https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20"
Response
application/json
{
  "data": [
    { … }
  ],
  "links": {
    "next": "https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20"
  }
}

Get token details

Request

Get a token by its identifier.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to read.

curl -i -X GET \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
idstring(uuid)required
Example: "8744c9ea-a02b-4ae6-875c-b64fc333e3ef"
cardobjectrequired
Example: {"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"}
card.​cardholder_namestring
Example: "John Doe"
card.​expiry_monthintegerrequired
Example: 12
card.​expiry_yearintegerrequired
Example: 2025
card.​masked_account_numberstringrequired
Example: "411111******1111"
card.​schemestringrequired
Enum"visa""mastercard""american express""discover""diners club""jcb""unionpay"
Example: "visa"
created_atstring(date-time)required
Example: "2023-10-01T12:00:00Z"
metadataobject
expires_atstring(data-time)
Response
application/json
{
  "id": "8744c9ea-a02b-4ae6-875c-b64fc333e3ef",
  "card": {
    "cardholder_name": "John Doe",
    "expiry_month": 12,
    "expiry_year": 2025,
    "masked_account_number": "411111******1111",
    "scheme": "visa"
  },
  "created_at": "2023-10-01T12:00:00Z"
}

Delete a token

Request

Remove a token from the system.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to delete.

curl -i -X DELETE \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response (No Content)

Response
No content

Check security code

Request

Check if the security code is still available for the token.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to check.

curl -i -X GET \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}/security-code' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
security_code_availablebooleanrequired

Indicates whether the security code is available for the token.

Response
application/json
{
  "security_code_available": true
}

Refresh security code

Request

Request a refresh of the security code for the token.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to check.

Headers
x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001
curl -i -X POST \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}/security-code' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001'

Responses

Success response

Bodyapplication/json
session_idstring(uuid)required
Response
application/json
{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Delete security code

Request

Remove the security code for the token.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to delete the security code for.

curl -i -X DELETE \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}/security-code' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response (No Content)

Response
No content

Foward card data

Request

This endpoint allows to securely forward cardholder data to a certified third-party provider. It will inject sensitive cardholder data from the PCI token into the request before forwarding it.

Guardian forwards all headers from the request, except those it uses internally. To override these internal headers, you can provide a key-value pair that replaces the original header with your custom value.

The following example demonstrates this use case:

curl --location 'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/8744c9ea-a02b-4ae6-875c-b64fc333e3ef/forward' \
--header 'x-api-key: hlg-sbx-9876...'
--header 'x-own-header-name: x-api-key' \
--header 'x-own-header-value: 123456...' \
...

In the forwarded call, a header x-api-key: 123456... will be set, replacing the Guardian's x-api-key header.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to forward.

Headers
x-destination-urlstring(uri)

The target URL to which the request shall be forwarded.

Important information

Guardian forwards calls only to whitelisted destination URLs. We include all major payment providers by default. In case you want to forward calls to a custom URL, please contact our support team to get the URL whitelisted.

Body
object

The payload the caller wants to forward to the third party provider.

To securely handle and inject sensitive cardholder data, predefined templates can be used. These templates help structure and standardize the data injection process while ensuring compliance with security and regulatory requirements.

PlaceholderDescription
{{ account_number }}The actual full account number of the stored card.
{{ cardholder_name }}The name of the cardholder.
{{ expiration_year }}Four digit year of the expiration date.
{{ expiration_month }}Two digit month of the expiration date.
{{ security_code }}The security code of the card in case it is present.

All injected data will be represented as a string in the payload. If a specific data type is required, such as a numeric representation of the expiration month, the data can be unwrapped and converted back to its original type as needed: {{ expiration_month | unwrap }}.

curl -i -X POST \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}/forward' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-destination-url: http://example.com' \
  -d '{
    "transactionReference": "My reference",
    "instruction": {
      "method": "card",
      "paymentInstrument": {
        "type": "plain",
        "cardNumber": "{{ account_number }}",
        "expiryDate": {
          "month": "{{ expiration_month | unwrap }}",
          "year": "{{ expiration_year | unwrap }}"
        }
      }
    },
    "value": {
      "currency": "EUR",
      "amount": 1000
    }
  }'

Responses

Success response

Body
object

The response from the third party provider.

Response
{}

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

Administration

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

Operations
Starfish GmbH & Co. KG © 2025