# 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](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
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
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`.


```bash
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 |
|  --- | --- | --- |
| `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
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
{
  "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.

Invalid Requests - HTTP 4xx
The response payload for processing errors follows a standard format.


```json
{
  "status": "the HTTP status code",
  "classifier": "the classifier of the error",
  "message": "interesting for humans..."
}
```

Unprocessable Content - HTTP 422
The response payload for validation errors follows a standard
format which includes the validation errors.


```json
{
  "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
- 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+)