openapi: 3.0.3
info:
  title: Guardian API
  version: EAP
  contact:
    name: Starfish GmbH & Co. KG
    email: hello@starfish.team
    url: https://hellgate.io/guardian
  license:
    name: Hellgate API Terms
    url: https://hellgate.io/terms-and-conditions-24-04
  description: >-
    # Getting started


    {% admonition type="info" name="Guardian Early Access Program" %}

    Guardian in its CPA version is currently in early access. You can apply for
    access by contacting your account representative.

    {% /admonition %}


    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:


    {% table %}


    - Parameter {% width="15%" %}

    - Type {% width="20%" %}

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


    {% /table %}


    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.


    {% tabs %}
      {% tab label="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..."
        }
        ```
      {% /tab %}
      {% tab label="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..."
            }
          ]
        }
        ```
      {% /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+)
servers:
  - url: https://{cluster_id}.on-hellgate.cloud
    description: Managed instance of Guardian CPA
    variables:
      cluster_id:
        default: my-cluster-id
        description: |
          Guardian CPA is provided as dedicated managed infrastructure. 
          The unique cluster-id is used to connect to your instance.
tags:
  - name: pci
    x-displayName: PCI Tokens
    description: Management of card payment credentials under the ruling of PCI/DSS.
  - name: network
    x-displayName: Network Tokens
    description: >-
      Management of network tokens, including cryptograms for secure
      transactions.
  - name: metadata
    x-displayName: Metadata Inquiries
    description: Inquiries for card metadata based on PAN, PCI tokens, or network tokens.
  - name: admin
    x-displayName: Administration
    description: >-
      Administrative operations for managing a Guardian instance, such as API
      keys.
paths:
  /api/pci/tokens:
    post:
      summary: Create token
      description: >
        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:


        {% table %}


        - Source {% width="20%" %}

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


        {% /table %}
      operationId: pci_token_create
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: x-idempotency-key
          in: header
          description: Optional idempotency key to prevent duplicate processing
          required: false
          schema:
            type: string
            example: order_12345_retry_001
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token_create_request'
            examples:
              session:
                summary: Session as Source (SAQ-A+)
                value:
                  source:
                    type: session
              pan:
                summary: PAN as Source (SAQ-D+)
                value:
                  source:
                    type: pan
                    account_number: '4111111111111111'
                    expiry_month: 12
                    expiry_year: 2025
                    security_code: '123'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token_create_response'
              examples:
                session:
                  summary: Session as Source (SAQ-A+)
                  value:
                    session_id: 8744c9ea-a02b-4ae6-875c-b64fc333e3ef
                pan:
                  summary: PAN as Source (SAQ-D+)
                  value:
                    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'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    get:
      summary: Get tokens
      description: List all tokens in the PCI/DSS scope.
      operationId: pci_token_list
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: after
          in: query
          description: >-
            The ID of the token after which to start listing. This is used for
            pagination.
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token_list'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /api/pci/tokens/{id}:
    get:
      summary: Get token details
      description: Get a token by its identifier.
      operationId: pci_token_get
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: id
          in: path
          description: The ID of the token to read.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete a token
      description: Remove a token from the system.
      operationId: pci_token_delete
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: id
          in: path
          description: The ID of the token to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /api/pci/tokens/{id}/security-code:
    get:
      summary: Check security code
      description: Check if the security code is still available for the token.
      operationId: pci_token_security_code_check
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: id
          in: path
          description: The ID of the token to check.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/security_code_response'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    post:
      summary: Refresh security code
      description: Request a refresh of the security code for the token.
      operationId: pci_token_security_code_refresh
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: id
          in: path
          description: The ID of the token to check.
          required: true
          schema:
            type: string
            format: uuid
        - name: x-idempotency-key
          in: header
          description: Optional idempotency key to prevent duplicate processing
          required: false
          schema:
            type: string
            example: order_12345_retry_001
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/session'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete security code
      description: Remove the security code for the token.
      operationId: pci_token_security_code_delete
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - pci
      parameters:
        - name: id
          in: path
          description: The ID of the token to delete the security code for.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /api/pci/tokens/{id}/forward:
    post:
      summary: Foward card data
      description: >
        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

        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.
      operationId: pci_token_forward
      tags:
        - pci
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - in: path
          name: id
          description: The ID of the token to forward.
          schema:
            type: string
            format: uuid
          required: true
        - in: header
          name: x-destination-url
          description: >
            The target URL to which the request shall be forwarded.


            {% admonition type="info" name="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.

            {% /admonition %}
          schema:
            type: string
            format: uri
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: >
                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. 


                | Placeholder              |
                Description                                          |

                |--------------------------|------------------------------------------------------|

                | `{{ 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 }}`.
            examples:
              worldpay:
                description: Forward a payment request to Worldpay
                value:
                  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
              adyen:
                description: Forward a payment request to Adyen
                value:
                  paymentMethod:
                    type: scheme
                    number: '{{ account_number }}'
                    expiryMonth: '{{ expiration_month}}'
                    expiryYear: '{{ expiration_year}}'
                    cvc: '{{ security_code }}'
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: >
                The content-type can also be `x-www-form-urlencoded`.


                In order to inject sensitive cardholder data templates can be
                used.


                | Placeholder              |
                Description                                          |

                |--------------------------|------------------------------------------------------|

                | `{{ 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. |
            examples:
              stripe:
                description: Forward a payment request to Stripe
                value:
                  paymentMethod:
                    type: card
                    card:
                      number: '{{ account_number }}'
                      exp_month: '{{ expiration_month}}'
                      exp_year: '{{ expiration_year}}'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                description: The response from the third party provider.
            application/x-www-form-urlencoded:
              schema:
                type: object
                description: The response from the third party provider.
        '400':
          $ref: '#/components/responses/400_BadRequestError'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '407':
          $ref: '#/components/responses/407_ProxyAuthenticationRequiredError'
        '502':
          $ref: '#/components/responses/502_BadGatewayError'
        '503':
          $ref: '#/components/responses/503_ServiceUnavailableError'
        '504':
          $ref: '#/components/responses/504_GatewayTimeoutError'
  /api/network/tokens:
    post:
      summary: Create token
      description: >
        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:


        {% table %}


        - Source {% width="20%" %}

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


        {% /table %}


        {% admonition type="info" name="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.
        {% /admonition %}
      operationId: network_token_create
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - network
      parameters:
        - name: x-idempotency-key
          in: header
          description: Optional idempotency key to prevent duplicate processing
          required: false
          schema:
            type: string
            example: order_12345_retry_001
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token_create_request-2'
            examples:
              session:
                summary: Session as Source (SAQ-A+)
                value:
                  source:
                    type: session
              pan:
                summary: PAN as Source (SAQ-D+)
                value:
                  source:
                    type: pan
                    account_number: '4111111111111111'
                    expiry_month: 12
                    expiry_year: 2025
                    security_code: '123'
              pci_token:
                summary: PCI Token as Source (SAQ-A+)
                value:
                  source:
                    type: pci_token
                    pci_token_id: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token_create_response-2'
              examples:
                session:
                  summary: Session as Source (SAQ-A+)
                  value:
                    session_id: 8744c9ea-a02b-4ae6-875c-b64fc333e3ef
                pan:
                  summary: PAN as Source (SAQ-D+)
                  value:
                    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
                pci_token:
                  summary: PCI Token as Source (SAQ-A+)
                  value:
                    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
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    get:
      summary: Get tokens
      description: List all network tokens.
      operationId: network_token_list
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - network
      parameters:
        - name: after
          in: query
          description: >-
            The ID of the token after which to start listing. This is used for
            pagination.
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token_list-2'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /api/network/tokens/{id}:
    get:
      summary: Get token details
      description: Retrieves details of a specific network token by its ID.
      operationId: network_token_get
      tags:
        - network
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          description: The ID of the token to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token-2'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete token
      description: Deletes a specific network token by its ID.
      operationId: network_token_delete
      tags:
        - network
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          description: The ID of the token to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /api/network/tokens/{id}/cryptograms:
    post:
      summary: Request cryptogram
      description: >
        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:


        {% table %}


        - Type {% width="20%" %}

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


        {% /table %}
      operationId: network_token_cryptogram
      tags:
        - network
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          description: The ID of the token for which to request a cryptogram.
          required: true
          schema:
            type: string
            format: uuid
        - name: x-idempotency-key
          in: header
          description: Optional idempotency key to prevent duplicate processing
          required: false
          schema:
            type: string
            example: order_12345_retry_001
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cryptogram_request'
            examples:
              ecom:
                summary: E-commerce request
                value:
                  type: ecom
                  amount: 1000
                  currency_code: EUR
                  reference: order_1234567890
              dauth:
                summary: Delegated authentication request
                value:
                  type: dauth
                  amount: 1000
                  currency_code: EUR
                  data: 0sxO1Q4+VME7xw7nwWJbagvHhu85JlJzQuMx+RuWL90=
                  dynamic_data:
                    delegated_authentication: true
                    authentication_factor_a: X
                    authentication_factor_b: 'Y'
                  framework: visa_vts
                  reference: order_1234567890
      responses:
        '200':
          description: Success response with the requested cryptogram.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cryptogram_response'
        '400':
          $ref: '#/components/responses/400_BadRequestError'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /api/metadata/inquiries:
    post:
      summary: Create inquiry
      description: >-
        Create a new inquiry for card metadata based on either a PAN, an
        existing PCI token, or a network token.
      operationId: inquiry_create
      security:
        - APIKey: []
        - AdminToken: []
      tags:
        - metadata
      parameters:
        - name: x-idempotency-key
          in: header
          description: Optional idempotency key to prevent duplicate processing
          required: false
          schema:
            type: string
            example: order_12345_retry_001
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inquiry_request'
            examples:
              inquiry_from_pan:
                summary: Inquiry from PAN (SAQ D+)
                value:
                  source:
                    type: pan
                    account_number: '4111111111111111'
                    expiry_month: 12
                    expiry_year: 2025
                    security_code: '123'
              inquiry_from_pci_token:
                summary: Inquiry from PCI token (SAQ A+)
                value:
                  source:
                    type: pci_token
                    pci_token_id: 123e4567-e89b-12d3-a456-426614174000
              inquiry_from_network_token:
                summary: Inquiry from network token (SAQ A+)
                value:
                  source:
                    type: network_token
                    network_token_id: 123e4567-e89b-12d3-a456-426614174001
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inquiry_response'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /api/admin/api-keys:
    post:
      summary: Create API key
      description: Creates a new API key with the specified scopes and expiration time.
      operationId: admin_api_key_create
      tags:
        - admin
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: x-idempotency-key
          in: header
          description: Optional idempotency key to prevent duplicate processing
          required: false
          schema:
            type: string
            example: order_12345_retry_001
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api_key_create_request'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_key_create_response'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    get:
      summary: Get API keys
      description: Retrieves a list of all API keys.
      operationId: admin_api_key_list
      tags:
        - admin
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: after
          in: query
          description: >-
            The ID of the API key after which to start listing. This is used for
            pagination.
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_key_list'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /api/admin/api-keys/{id}:
    get:
      summary: Get API key details
      description: Retrieves detailed information about a specific API key.
      operationId: admin_api_key_get
      tags:
        - admin
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the API key.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_key'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    patch:
      summary: Update API key
      description: Updates the scopes of an existing API key.
      operationId: admin_api_key_update
      tags:
        - admin
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the API key.
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api_key_update_request'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_key'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    delete:
      summary: Delete API key
      description: Deletes a specific API key.
      operationId: admin_api_key_delete
      tags:
        - admin
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the API key.
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
components:
  securitySchemes:
    APIKey:
      type: apiKey
      name: x-api-key
      in: header
    AdminToken:
      type: apiKey
      name: x-admin-token
      in: header
  schemas:
    card:
      type: object
      properties:
        cardholder_name:
          type: string
        expiry_month:
          type: integer
        expiry_year:
          type: integer
        masked_account_number:
          type: string
        scheme:
          type: string
          enum:
            - visa
            - mastercard
            - american express
            - discover
            - diners club
            - jcb
            - unionpay
      required:
        - expiry_month
        - expiry_year
        - masked_account_number
        - scheme
      example:
        cardholder_name: John Doe
        expiry_month: 12
        expiry_year: 2025
        masked_account_number: 411111******1111
        scheme: visa
    token:
      type: object
      properties:
        id:
          type: string
          format: uuid
        card:
          $ref: '#/components/schemas/card'
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
        expires_at:
          type: string
          format: data-time
      required:
        - id
        - card
        - created_at
      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'
    token_list:
      type: object
      properties:
        data:
          type: array
          items:
            - $ref: '#/components/schemas/token'
        links:
          type: object
          properties:
            next:
              type: string
              format: uri
          required:
            - next
      required:
        - data
        - links
      example:
        data:
          - 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'
        links:
          next: >-
            https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20
    ErrorStatusCode:
      type: integer
      description: The corresponding HTTP status code for the error
    ErrorClassifier:
      type: string
      description: Technical code that helps to identify the error
    ErrorMessage:
      type: string
      description: Human readable representation of the error
    ErrorGeneric:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
    from_session_source:
      type: object
      properties:
        type:
          type: string
      required:
        - type
    from_pan_source:
      type: object
      properties:
        type:
          type: string
        account_number:
          type: string
        cardholder_name:
          type: string
        expiry_year:
          type: integer
        expiry_month:
          type: integer
        security_code:
          type: string
      required:
        - type
        - account_number
        - expiry_year
        - expiry_month
    token_create_request:
      type: object
      properties:
        expiration_time:
          type: integer
          minimum: 1
          maximum: 2592000
          description: |
            The expiry time is used to specify after how many seconds 
            a token should be automatically deleted after creation.
        metadata:
          type: object
          description: |
            Key-value pairs (max 20) with max 100 chars each pair.
        source:
          discriminator:
            propertyName: type
            mapping:
              session: '#/components/schemas/from_session_source'
              pan: '#/components/schemas/from_pan_source'
          default: session
          oneOf:
            - $ref: '#/components/schemas/from_session_source'
            - $ref: '#/components/schemas/from_pan_source'
      required:
        - source
    session:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
      required:
        - session_id
    token_create_response:
      type: object
      oneOf:
        - $ref: '#/components/schemas/session'
        - $ref: '#/components/schemas/token'
    ErrorValidation:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        validation_errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: Json-path in the request which points to the validation error
              message:
                type: string
                description: Human readable validation message
    security_code_response:
      type: object
      properties:
        security_code_available:
          type: boolean
          description: Indicates whether the security code is available for the token.
      required:
        - security_code_available
    token-2:
      type: object
      properties:
        id:
          type: string
          format: uuid
        card:
          $ref: '#/components/schemas/card'
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
        network_token:
          type: object
          properties:
            number:
              type: string
            expiry_month:
              type: integer
            expiry_year:
              type: integer
            status:
              type: string
              enum:
                - active
                - inactive
                - deleted
          required:
            - number
            - expiry_month
            - expiry_year
            - status
      required:
        - id
        - card
        - created_at
        - network_token
      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
    token_list-2:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/token-2'
        links:
          type: object
          properties:
            next:
              type: string
              description: The URL to the next page of results, if available.
              format: uri
          required:
            - next
      required:
        - data
        - links
      example:
        data:
          - 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
        links:
          next: >-
            https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20
    from_pci_token_source:
      type: object
      properties:
        type:
          type: string
        pci_token_id:
          type: string
          format: uuid
      required:
        - type
        - pci_token_id
    token_create_request-2:
      type: object
      properties:
        metadata:
          type: object
          description: |
            Key-value pairs (max 20) with max 100 chars each pair.
        source:
          type: object
          discriminator:
            propertyName: type
            mapping:
              session: '#/components/schemas/from_session_source'
              pan: '#/components/schemas/from_pan_source'
              pci_token: '#/components/schemas/from_pci_token_source'
          oneOf:
            - $ref: '#/components/schemas/from_session_source'
            - $ref: '#/components/schemas/from_pan_source'
            - $ref: '#/components/schemas/from_pci_token_source'
      required:
        - source
    token_create_response-2:
      type: object
      oneOf:
        - $ref: '#/components/schemas/session'
        - $ref: '#/components/schemas/token-2'
    cryptogram_request_ecom:
      type: object
      properties:
        type:
          type: string
        amount:
          type: integer
          description: >
            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_code:
          type: string
          description: |
            The three letter ISO-4217 currency code.
        reference:
          type: string
      required:
        - amount
        - currency_code
        - reference
    cryptogram_request_dauth:
      type: object
      properties:
        type:
          type: string
        amount:
          type: integer
          description: >
            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_code:
          type: string
          description: |
            The three letter ISO-4217 currency code.
        data:
          type: string
        dynamic_data:
          type: object
          properties:
            delegated_authentication:
              type: boolean
            authentication_factor_a:
              type: string
            authentication_factor_b:
              type: string
          required:
            - delegated_authentication
            - authentication_factor_a
            - authentication_factor_b
        framework:
          type: string
          enum:
            - visa_vts
            - mastercard_taf
        reference:
          type: string
      required:
        - amount
        - currency_code
        - data
        - dynamic_data
        - framework
        - reference
    cryptogram_request:
      discriminator:
        propertyName: type
        mapping:
          ecom: '#/components/schemas/cryptogram_request_ecom'
          dauth: '#/components/schemas/cryptogram_request_dauth'
      oneOf:
        - $ref: '#/components/schemas/cryptogram_request_ecom'
        - $ref: '#/components/schemas/cryptogram_request_dauth'
    cryptogram_response:
      type: object
      properties:
        cryptogram:
          type: string
          description: >
            The token authentication verification value (TAVV) for the network
            token.
        eci:
          type: string
          description: |
            The Electronic Commerce Indicator (ECI) from the issuer.
      example:
        cryptogram: Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB
        eci: '05'
    from_network_token_source:
      type: object
      properties:
        type:
          type: string
        network_token_id:
          type: string
          format: uuid
      required:
        - type
        - network_token_id
    inquiry_request:
      type: object
      properties:
        source:
          type: object
          discriminator:
            propertyName: type
            mapping:
              pan: '#/components/schemas/from_pan_source'
              pci_token: '#/components/schemas/from_pci_token_source'
              network_token: '#/components/schemas/from_network_token_source'
          oneOf:
            - $ref: '#/components/schemas/from_pan_source'
            - $ref: '#/components/schemas/from_pci_token_source'
            - $ref: '#/components/schemas/from_network_token_source'
      required:
        - source
    inquiry_response:
      type: object
      properties:
        bin:
          type: string
          minLength: 6
          maxLength: 8
        scheme:
          type: string
          enum:
            - visa
            - mastercard
            - american express
            - discover
            - diners club
            - jcb
            - unionpay
        type:
          type: string
          enum:
            - credit
            - debit
            - prepaid
            - other
        segment:
          type: string
          enum:
            - consumer
            - commercial
        billing_currency_code:
          type: string
          minLength: 3
          maxLength: 3
        issuer_name:
          type: string
        issuer_country_code:
          type: string
        product_code:
          type: string
        product_name:
          type: string
      required:
        - bin
        - scheme
      example:
        bin: '411111'
        scheme: visa
        type: credit
        segment: consumer
        billing_currency_code: EUR
        issuer_name: Starfish Bank
        issuer_country_code: DE
        product_code: VISA-PLATINUM
        product_name: Visa Platinum Card
    scopes:
      type: array
      description: A list of scopes that the API key will have access to.
      minItems: 1
      items:
        type: string
        enum:
          - admin:api-keys:create
          - admin:api-keys:read
          - admin:api-keys:update
          - admin:api-keys:delete
          - pci:tokens:create
          - pci:tokens:read
          - pci:tokens:update
          - pci:tokens:delete
          - pci:tokens:forward
          - network:tokens:create
          - network:tokens:read
          - network:tokens:delete
          - network:tokens:use
          - metadata:inquiry:create
    api_key:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        masked_key_value:
          type: string
        scopes:
          $ref: '#/components/schemas/scopes'
      required:
        - id
        - created_at
        - masked_key_value
        - scopes
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        created_at: '2023-10-01T12:00:00Z'
        masked_key_value: key_123xxxx
        scopes:
          - admin:api-keys:create
          - admin:api-keys:update
    api_key_list:
      type: object
      properties:
        data:
          type: array
          items:
            - $ref: '#/components/schemas/api_key'
        links:
          type: object
          properties:
            next:
              type: string
              format: uri
          required:
            - next
      required:
        - data
        - links
      example:
        data:
          - id: 123e4567-e89b-12d3-a456-426614174000
            created_at: '2023-10-01T12:00:00Z'
            masked_key_value: key_123xxxx
            scopes:
              - admin:api-keys:create
              - admin:api-keys:update
        links:
          next: >-
            https://my-cluster-id.on-hellgate.cloud/admin/api-keys?after=123e4567-e89b-12d3-a456-426614174000&limit=20
    api_key_create_request:
      type: object
      properties:
        expiration_time:
          type: integer
          minimum: 1
          maximum: 7776000
          description: >
            Specifies how many seconds after creation the API key will expire
            automatically.
        scopes:
          $ref: '#/components/schemas/scopes'
      required:
        - scopes
      example:
        expiration_time: 3600
        scopes:
          - admin:api-keys:create
          - admin:api-keys:update
    api_key_create_response:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        key_value:
          type: string
          description: >-
            The generated API key value. It will only be returned once with this
            response.
        scopes:
          $ref: '#/components/schemas/scopes'
      required:
        - id
        - created_at
        - key_value
        - scopes
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        created_at: '2023-10-01T10:00:00Z'
        expires_at: '2023-10-01T11:00:00Z'
        key_value: key_1234567890ABCDEF
        scopes:
          - admin:api-keys:create
          - admin:api-keys:update
    api_key_update_request:
      type: object
      properties:
        scopes:
          $ref: '#/components/schemas/scopes'
      required:
        - scopes
      example:
        scopes:
          - admin:api-keys:create
          - admin:api-keys:update
  responses:
    401_UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 401
            message: No valid means of authentication was provided
            classifier: UNAUTHORIZED
    403_ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 403
            message: Not allowed to access this resource or feature
            classifier: FORBIDDEN
    409_ConflictError:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 409
            message: Conflict
            classifier: CONFLICT
    422_ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorValidation'
          example:
            code: 422
            classifier: VALIDATION_ERROR
            message: Validation error
            validation_errors:
              - path: json-path
                message: human readable error message
    404_NotFoundError:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 404
            message: The requested resource was not found.
            classifier: NOT_FOUND
    400_BadRequestError:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 400
            message: The request could not be handle due to invalid data
            classifier: BAD_REQUEST
    407_ProxyAuthenticationRequiredError:
      description: No valid means of authentication was provided for the proxy
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 407
            message: Proxy authentication required
            classifier: PROXY_AUTHENTICATION_REQUIRED
    502_BadGatewayError:
      description: A non-processable response was received from the upstream server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 502
            message: Bad gateway
            classifier: BAD_GATEWAY
    503_ServiceUnavailableError:
      description: The server is currently not able to handle the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 503
            message: Service unavailable
            classifier: SERVICE_UNAVAILABLE
    504_GatewayTimeoutError:
      description: The server did not receive any response in time from the upstream server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 504
            message: Gateway timeout
            classifier: GATEWAY_TIMEOUT
