openapi: 3.0.3
info:
  title: Guardian API
  version: EAP
  contact:
    name: Starfish GmbH & Co. KG
    email: hello@starfish.team
    url: https://hellgate.io/cpa/guardian
  license:
    name: Hellgate API Terms
    url: https://hellgate.io/terms-and-conditions
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: apikey
    x-displayName: API Keys
    description: |
      Management of API keys for service access.

      The capabilities an API keys has access to can be scoped to these areas:

        - API Keys
          - `admin:api-keys:create`
          - `admin:api-keys:read`
          - `admin:api-keys:update`
          - `admin:api-keys:delete`
        - Webhooks
          - `admin:webhooks:create`
          - `admin:webhooks:read`
          - `admin:webhooks:delete`
        - PCI Tokens
          - `pci:tokens:create`
          - `pci:tokens:read`
          - `pci:tokens:update`
          - `pci:tokens:delete`
          - `pci:tokens:forward`
        - Network Tokens
          - `network:tokens:create`
          - `network:tokens:read`
          - `network:tokens:delete`
          - `network:tokens:use`
        - Metadata Inquiries
          - `metadata:inquiry:create`
  - name: webhook
    x-displayName: Webhooks
    description: >
      Management of webhooks for event notifications.


      Guardian uses tiny events as notification payload. They give you the
      context of what happened and you

      can use this information to fetch more details via our API.


      Please find the documentation about the callback on the endpoint that
      registers the webhook.
x-tagGroups:
  - name: Tokens
    tags:
      - pci
      - network
  - name: Add-ons
    tags:
      - metadata
  - name: Admin
    tags:
      - apikey
      - webhook
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: limit
          in: query
          description: >
            The limit parameter defines the maximum number of rows returned in a
            single call and enables 

            consecutive pagination using the `next` link provided in the
            response payload.
          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.                          |

                | `{{ expiry_year }}`      | Four digit year of the expiry
                date.                  |

                | `{{ expiry_month }}`     | Two digit month of the expiry
                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 expiry
                month, the data 

                can be unwrapped and converted back to its original type as
                needed: `{{ expiry_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: '{{ expiry_month | unwrap }}'
                        year: '{{ expiry_year | unwrap }}'
                  value:
                    currency: EUR
                    amount: 1000
              adyen:
                description: Forward a payment request to Adyen
                value:
                  paymentMethod:
                    type: scheme
                    number: '{{ account_number }}'
                    expiryMonth: '{{ expiry_month}}'
                    expiryYear: '{{ expiry_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.                          |

                | `{{ expiry_year }}`      | Four digit year of the expiry
                date.                  |

                | `{{ expiry_month }}`     | Two digit month of the expiry
                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: '{{ expiry_month}}'
                      exp_year: '{{ expiry_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:
                      status: active
                      type: vts
                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:
                      status: active
                      type: vts
        '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: limit
          in: query
          description: >
            The limit parameter defines the maximum number of rows returned in a
            single call and enables 

            consecutive pagination using the `next` link provided in the
            response payload.
          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'
                  merchant_name: Example Merchant
                  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/network/tokens/{id}/card-art:
    get:
      summary: Get card art
      description: Get the card art associated with the network token.
      operationId: network_token_card_art
      tags:
        - network
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          description: The ID of the token for which to request the card art.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_art'
        '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 expiry defined via
        `expires_in` (seconds).
      operationId: admin_api_key_create
      tags:
        - apikey
      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:
        - apikey
      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:
        - apikey
      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:
        - apikey
      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:
        - apikey
      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'
  /api/admin/webhooks:
    post:
      summary: Register webhook
      description: Register a new webhook and receive callbacks.
      operationId: admin_webhook_create
      tags:
        - webhook
      security:
        - APIKey: []
        - AdminToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_create_request'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
              example:
                id: 5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
                created_at: '2023-10-05T14:48:00.000Z'
                url: https://my-webhook-endpoint.com/webhooks
                events:
                  - network.token.updated
                  - pci.token.security-code.expired
                masekd_hmac_key: 123xxxx
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        onEvent:
          '{$request.body#/url}':
            post:
              summary: Event notification callback
              description: >
                This callback is sent by the server to the client's webhook URL
                when a 

                subscribed event occurs.
              security: []
              parameters:
                - in: header
                  name: x-hmac-signature
                  schema:
                    type: string
                  description: >
                    The signature of request body calculated based on the secret
                    HMAC key of the account  
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/event_payload'
              responses:
                '200':
                  description: >
                    Confirmation of receipt. For other status codes, the system
                    will try to redeliver.
                '400':
                  description: Bad request
    get:
      summary: Get webhooks
      description: List all webhooks known to the system.
      operationId: admin_webhook_list
      tags:
        - webhook
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: limit
          in: query
          description: >
            The limit parameter defines the maximum number of rows returned in a
            single call and enables 

            consecutive pagination using the `next` link provided in the
            response payload.
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_list'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /api/admin/webhooks/{id}:
    get:
      summary: Get webhook details
      description: Retrieves detailed information about a specific webhook.
      operationId: admin_webhook_get
      tags:
        - webhook
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the webhook.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete webhook
      description: Deletes a specific webhook.
      operationId: admin_webhook_delete
      tags:
        - webhook
      security:
        - APIKey: []
        - AdminToken: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the webhook.
          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
    Metadata:
      type: object
      description: >
        Metadata consisting of entries, each of which each includes a key and an
        associated value:

          * Maximum 20 key-value pairs.
          * Maximum 20 characters per key.
          * Maximum 80 characters per value.
      example:
        my_key_one: my_value_one
        my_key_two: my_value_two
    token:
      type: object
      properties:
        id:
          type: string
          format: uuid
        card:
          $ref: '#/components/schemas/card'
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        metadata:
          $ref: '#/components/schemas/Metadata'
      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
          description: The card number (without separators)
          example: '4111111111111111'
        cardholder_name:
          type: string
          description: The name of the cardholder
          example: Bob Holder
        expiry_year:
          type: integer
          description: The expiry year of the card
          minimum: 2000
          example: 2025
        expiry_month:
          type: integer
          description: The expiry month of the card
          minimum: 1
          maximum: 12
          example: 4
        security_code:
          type: string
          minLength: 3
          maxLength: 4
          example: '321'
          description: |
            The security code of the card

            {% admonition type="info" name="Information" %}
              The system will not permanently store the security code, but keep it in a ephemeral position for immediate use.
            {% /admonition %}
      required:
        - type
        - account_number
        - expiry_year
        - expiry_month
    token_create_request:
      type: object
      properties:
        expires_in:
          type: integer
          minimum: 1
          maximum: 2592000
          description: |
            How many seconds after creation the token expires automatically.
        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'
        metadata:
          $ref: '#/components/schemas/Metadata'
      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
        network_token:
          type: object
          properties:
            scheme_reference:
              type: string
              description: >
                The ID of the network token at the scheme. 


                This value is only present if Delegated Authentication is active
                for the instance.
            status:
              type: string
              enum:
                - active
                - inactive
                - deleted
            type:
              type: string
              description: The network token type.
              enum:
                - vts
                - mdes
                - tms
          required:
            - status
            - type
        pci_token_id:
          type: string
          format: uuid
          description: The ID of the PCI token that represents the `card`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - card
        - created_at
        - network_token
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        created_at: '2023-10-01T12:00:00Z'
        card:
          cardholder_name: John Doe
          expiry_month: 12
          expiry_year: 2025
          masked_account_number: 411111******1111
          scheme: visa
        network_token:
          status: active
          type: vts
        pci_token_id: 32e4567-e89b-12d3-a456-426614174000
    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:
              status: active
              type: vts
        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:
        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'
        metadata:
          $ref: '#/components/schemas/Metadata'
      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
        metadata:
          $ref: '#/components/schemas/Metadata'
      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
          description: Signature data from the device.
        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
        merchant_name:
          type: string
          description: >-
            The name of the merchant associated with the delegated
            authentication.
        reference:
          type: string
          description: |
            A reference for the cryptogram request, e.g. an order number.

            {% admonition type="info" %}
              On VISA this field must only contain: letters, numbers, and hyphens.
            {% /admonition %}
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - amount
        - currency_code
        - data
        - dynamic_data
        - 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.
        expiry_month:
          type: integer
        expiry_year:
          type: integer
        number:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - cryptogram
        - eci
        - expiry_month
        - expiry_year
        - number
      example:
        cryptogram: Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB
        eci: '05'
        expiry_month: 10
        expiry_year: 2030
        number: '4122234533471157'
    card_art:
      type: object
      properties:
        base64_card_art:
          type: string
          format: base64
          description: The base64 encoded image
        height:
          type: integer
          description: Height of the image
        width:
          type: integer
          description: Width of the image
        mime_type:
          type: string
          description: MimeType of the image
    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
          description: The bank identification number.
        scheme:
          type: array
          description: >
            Scheme defines the brand of the card. A co-branded card will return
            multiple schemes.
          items:
            type: string
            enum:
              - visa
              - mastercard
              - american express
              - discover
              - diners club
              - jcb
              - unionpay
              - cartes bancaires
              - airplus
        type:
          type: string
          description: The funding type of the card.
          enum:
            - credit
            - debit
            - prepaid
            - charge
            - deferred
            - unknown
        segment:
          type: string
          description: The segment or category of the card.
          enum:
            - consumer
            - commercial
        currency_code:
          type: string
          description: |
            The three letter currency code of the card.
            See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)
          minLength: 3
          maxLength: 3
        issuer_name:
          type: string
          description: The name of the issuing bank.
        issuer_country_code:
          type: string
          description: >
            A two letter country code of the issuer.

            [ISO 3166-1
            alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
          minLength: 2
          maxLength: 2
      required:
        - bin
        - scheme
      example:
        bin: '411111'
        scheme:
          - visa
        type: credit
        segment: consumer
        currency_code: EUR
        issuer_name: Starfish Bank
        issuer_country_code: DE
    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
          - admin:webhooks:create
          - admin:webhooks:read
          - admin:webhooks: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:
        expires_in:
          type: integer
          minimum: 1
          maximum: 7776000
          description: |
            How many seconds after creation the API key expires automatically.
        scopes:
          $ref: '#/components/schemas/scopes'
      required:
        - scopes
      example:
        expires_in: 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
    event_type:
      type: string
      enum:
        - network.token.updated
        - pci.token.security-code.expired
      description: The type of event that occurred.
    webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the webhook.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the webhook was created.
        events:
          type: array
          items:
            $ref: '#/components/schemas/event_type'
          minItems: 1
          description: The list of events the webhook is subscribed to.
        masekd_hmac_key:
          type: string
          example: 123xxxx
          description: >-
            The masked HMAC key used to sign the payloads sent to the webhook
            URL.
        url:
          type: string
          format: uri
          description: The URL to which the webhook sends event notifications.
      required:
        - id
        - created_at
        - url
        - events
    webhook_list:
      type: object
      properties:
        data:
          type: array
          items:
            - $ref: '#/components/schemas/webhook'
        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_hmac_key: 123xxxx
            events:
              - network.token.updated
            url: https://example.com/webhook
        links:
          next: >-
            https://my-cluster-id.on-hellgate.cloud/admin/webhooks?after=123e4567-e89b-12d3-a456-426614174000&limit=20
    webhook_create_request:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/event_type'
          minItems: 1
          description: The list of events to subscribe to.
        hmac_key:
          type: string
          description: >-
            The HMAC key to be used to sign the payloads sent to the webhook
            URL.
        url:
          type: string
          format: uri
          description: The URL to which the webhook will send event notifications.
      required:
        - url
        - events
    event_payload:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the event.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the event was created.
        type:
          $ref: '#/components/schemas/event_type'
        reason:
          type: string
          description: A human readable reason description why the event was triggered.
          example: The scheme updated the network token.
        related_object:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: The ID of the resource on which the event was triggered.
              example: 5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
            url:
              type: string
              format: uri
              description: A link to the exact resource.
              example: >-
                https://my-instance-8765.on-hellgate.cloud/api/network/tokens/5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
          required:
            - id
            - url
      required:
        - id
        - created_at
        - type
        - reason
        - related_object
  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
