> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Information

> Essential information for using the Guardian API

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](https://en.wikipedia.org/wiki/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`.

```bash theme={null}
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`.

```bash theme={null}
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 the [Composable Payment Architecture (CPA)](/platform/cpa). 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:

| 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:

```bash theme={null}
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:

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Invalid Requests - HTTP 4xx">
    The response payload for processing errors follows a standard format.

    ```json theme={null}
    {
    "status": "the HTTP status code",
    "classifier": "the classifier of the error",
    "message": "interesting for humans..."
    }
    ```
  </Tab>

  <Tab title="Unprocessable Content - HTTP 422">
    The response payload for validation errors follows a standard
    format which includes the validation errors.

    ```json theme={null}
    {
    "status": "the HTTP status code",
    "classifier": "the classifier of the error",
    "message": "interesting for humans...",
    "validation_errors": [
        {
        "path": "a JSON path pointing to the wrong data",
        "message": "something interesting for humans..."
        }
    ]
    }
    ```
  </Tab>
</Tabs>

### 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+)