Create token

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

Create token

Request

Create and provision a new network token with a card scheme.

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

Source	Compliance	Description
`session`	Min. 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.
`pan`	Min. 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.
`pci_token`	Min. SAQ-A+	Use an existing PCI token as source. The network token will be provisioned independently from the PCI token, such that the life-cycles of the tokens are not coupled.

Important information

Currently only Visa, Mastercard, American Express, and Discover are supported as card schemes. The network token will be provisioned with the card scheme.

Security

APIKey or AdminToken

Headers

x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001

Bodyapplication/json

metadataobject

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

sourceobjectrequired

source.typestringrequired

Discriminator

curl -i -X POST \
  https://my-cluster-id.on-hellgate.cloud/api/network/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 network tokens.

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/network/tokens?after=497f6eca-6276-4993-bfeb-53cbbbba6f08&limit=20' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json

dataArray of objectsrequired

Example: [{"id":"123e4567-e89b-12d3-a456-426614174000","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","network_token":{"number":"4122234533471157","expiry_month":12,"expiry_year":2027,"status":"active"}}]

data[].idstring(uuid)required

Example: "123e4567-e89b-12d3-a456-426614174000"

data[].cardobjectrequired

Example: {"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"}

data[].card.cardholder_namestring

Example: "John Doe"

data[].card.expiry_monthintegerrequired

Example: 12

data[].card.expiry_yearintegerrequired

Example: 2025

data[].card.masked_account_numberstringrequired

Example: "411111******1111"

data[].card.schemestringrequired

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

Example: "visa"

data[].created_atstring(date-time)required

Example: "2023-10-01T12:00:00Z"

data[].metadataobject

data[].network_tokenobjectrequired

Example: {"number":"4122234533471157","expiry_month":12,"expiry_year":2027,"status":"active"}

data[].network_token.numberstringrequired

Example: "4122234533471157"

data[].network_token.expiry_monthintegerrequired

Example: 12

data[].network_token.expiry_yearintegerrequired

Example: 2027

data[].network_token.statusstringrequired

Enum"active""inactive""deleted"

Example: "active"

linksobjectrequired

Example: {"next":"https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20"}

links.nextstring(uri)required

The URL to the next page of results, if available.

Example: "https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20"

Response

application/json

{
  "data": [
    { … }
  ],
  "links": {
    "next": "https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20"
  }
}

Get token details

Request

Retrieves details of a specific network token by its ID.

Security

APIKey or AdminToken

Path

idstring(uuid)required

The ID of the token to retrieve.

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

Responses

Success response.

Bodyapplication/json

idstring(uuid)required

Example: "123e4567-e89b-12d3-a456-426614174000"

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

network_tokenobjectrequired

Example: {"number":"4122234533471157","expiry_month":12,"expiry_year":2027,"status":"active"}

network_token.numberstringrequired

Example: "4122234533471157"

network_token.expiry_monthintegerrequired

Example: 12

network_token.expiry_yearintegerrequired

Example: 2027

network_token.statusstringrequired

Enum"active""inactive""deleted"

Example: "active"

Response

application/json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "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",
  "network_token": {
    "number": "4122234533471157",
    "expiry_month": 12,
    "expiry_year": 2027,
    "status": "active"
  }
}

Delete token

Request

Deletes a specific network token by its ID.

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/network/tokens/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response (No Content)

Response

No content

Request cryptogram

Request

Request a cryptogram (TAAV) for a given network token. The cryptogram is a dynamic value used to authenticate and authorize tokenized transactions, ensuring secure communication with the payment network.

Guardian supports two types of scenarios for cryptograms:

Type	Description
`ecom`	This type is used in standard e-commerce transactions when a network token is in use.
`dauth`	This type is based on a delegated authentication setup with the card schemes and requires prior activation.

Security

APIKey or AdminToken

Path

idstring(uuid)required

The ID of the token for which to request a cryptogram.

Headers

x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001

Bodyapplication/json

typestring

Discriminator

amountintegerrequired

The amount given in minor units (e.g. use 700 for 7€). Some currencies do not support minor units (e.g. Japanese Yen). In this case send in the full value, .i.e. 100 for 100 JPY.

currency_codestringrequired

The three letter ISO-4217 currency code.

referencestringrequired

curl -i -X POST \
  'https://my-cluster-id.on-hellgate.cloud/api/network/tokens/{id}/cryptograms' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001' \
  -d '{
    "type": "ecom",
    "amount": 1000,
    "currency_code": "EUR",
    "reference": "order_1234567890"
  }'

Responses

Success response with the requested cryptogram.

Bodyapplication/json

cryptogramstring

The token authentication verification value (TAVV) for the network token.

Example: "Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB"

ecistring

The Electronic Commerce Indicator (ECI) from the issuer.

Example: "05"

Response

application/json

{
  "cryptogram": "Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB",
  "eci": "05"
}

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

Guardian API (EAP)

Getting started

JSON Conventions

Authentication

API Keys

Admin Tokens

API Use

Cluster-based Deployment

Idempotency

Request Errors

Security Considerations

PCI Tokens

Network Tokens

Create token

Request

Responses

Was this helpful?

Get tokens

Request

Responses

Was this helpful?

Get token details

Request

Responses

Was this helpful?

Delete token

Request

Responses

Was this helpful?

Request cryptogram

Request

Responses

Was this helpful?

Metadata Inquiries

Administration

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

Create token

RequestExpand all

Responses

Was this helpful?

Get tokens

Request

Responses

Was this helpful?

Get token details

Request

Responses

Was this helpful?

Delete token

Request

Responses

Was this helpful?

Request cryptogram

Request

Responses

Was this helpful?

Metadata Inquiries

Administration

Request