> ## 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
export const RunInPostman = ({uid, title, workspace, children}) =>
{children}
;
This reference is essential for your comprehensive understanding of Guardian and successful integration with our secure card data vault service.
Every endpoint on this reference, generated from the same OpenAPI specification and grouped exactly as the
navigation here. Duplicate the **Dedicated instance — template** environment and set `instance` and `env`.
The Authorization tab is pre-configured for the OAuth2 client-credentials grant, so add `clientId`,
`clientSecret`, `audiences` and `scopes` to the environment and hit **Get New Access Token**. Both
`audiences` and `scopes` are space-delimited lists — name every instance the token may call. See
[Authentication](/platform/authentication).
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`.
* Temporal data is encoded in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) strings.
### Empty Strings and Omitted Fields
The empty string is not a value. A string field is either **omitted** or present with a **real value** — and
where a field is nullable, an explicit `null` unsets it. Never send `""`.
Where a field is validated as a string, `""` is rejected with **422 Unprocessable Entity** and a field error
on that path (see [Request Errors](#request-errors) for the response format). Not every field carries that
validation, so do not treat the rejection as a safety net: where it is absent, `""` is accepted and then
stored or forwarded verbatim — an empty string travels further into a request than a missing field ever does.
## Authentication
Guardian authenticates every request with an **OAuth2 access token** — a signed JWT — passed as a bearer
token. Request the token with the client-credentials grant against the platform
[Authentication API](/platform/api-reference/overview); the token's audience is your instance name, and its
scopes gate the endpoints it may call.
```bash theme={null}
curl --header 'Authorization: Bearer ' \
--request POST 'https://my-instance.eu1.on-hellgate.cloud/api/...'
```
Administrative endpoints use the same token carrying the relevant `admin:*` scope. See
[Authentication](/products/guardian/authentication) for the full scope reference.
### API keys (deprecated)
Guardian still accepts a long-lived instance key in the `x-api-key` header, so existing integrations keep
working. New integrations should use an access token instead.
```bash theme={null}
curl --header 'x-api-key: ' \
--request POST 'https://my-instance.eu1.on-hellgate.cloud/api/...'
```
The `x-admin-token` header it used to pair with has been replaced by scoped access tokens.
Credentials must be handled with care and kept secure. Never hardcode tokens or API keys in your source code —
keep them solely on your backend systems.
## API Use
### Instance URL
Guardian is provided as a service of the Hellgate Cloud Platform implementing the [Composable Payment Architecture (CPA)](/platform/cpa). Each instance is accessible at a unique host:
```
https://{instance}.eu1.on-hellgate.cloud
```
`{instance}` is your unique instance slug and `eu1` is the current environment; both are provided during onboarding.
### 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 'Authorization: Bearer ' \
'https://my-instance.eu1.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-instance.eu1.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.
```json theme={null}
{
"status": "the HTTP status code",
"classifier": "the classifier of the error",
"message": "interesting for humans..."
}
```
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..."
}
]
}
```
### Security Considerations
Guardian handles sensitive payment card data and requires strict security practices:
* All communication must use HTTPS
* Access tokens, and any remaining API keys, 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+)