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

# Get authentications

> Get a list of all the authentications for this account.
The results are grouped into pages. The caller can specify how many customers per page shall be listed (maximum is 500).


<Badge stroke icon="wrench" color="blue">Beta Feature</Badge>


## OpenAPI

````yaml /products/commerce/v2/openapi.yaml get /authentications
openapi: 3.1.0
info:
  title: Commerce API
  version: '2.0'
  description: >
    The Commerce V2 API provides a comprehensive payment orchestration platform
    designed to streamline and optimize payment processing for modern
    businesses. 

    Built with flexibility and security at its core, our API enables you to
    process payments, manage authentications, and handle cardholder data across
    multiple payment processors without vendor lock-in.
  contact:
    name: Starfish GmbH & Co. KG
    email: hello@starfish.team
    url: https://hellgate.io/cpa/commerce
  license:
    name: Commerce API Terms
    url: https://hellgate.io/terms-and-conditions
servers:
  - url: https://sandbox.hellgate.io
    description: Commerce SaaS Sandbox
  - url: https://api.hellgate.io
    description: Commerce SaaS Production
security: []
tags:
  - name: payments_ci
    description: >-
      Handle payment processing where the customer is actively present and
      authorizing the transaction.
  - name: payments_mi
    description: >-
      Process transactions without direct customer interaction at the time of
      payment.
  - name: payments_modifications
    description: >-
      Modify existing payment transactions after initial authorization (capture,
      void, refund).
  - name: payments_data
    description: >-
      Access comprehensive payment transaction data for reporting,
      reconciliation, and analysis.
  - name: refunds_data
    description: Access detailed refund transaction data for tracking and reconciliation.
  - name: authentications_ci
    description: >-
      Process EMVCo 3-D Secure authentication requests as standalone
      transactions (one-off, recurring, installment).
  - name: authentications_mi
    description: >-
      Process requestor-initiated EMVCo 3-D Secure authentication requests (3RI)
      as standalone transactions.
  - name: authentications_data
    description: Access the results of prior authentications for reference.
  - name: credentials_management
    description: >-
      Manage stored payment credentials for repeat customers across all
      operating models.
  - name: tokens_create
    description: >-
      Create and import Commerce tokens to securely store cardholder data while
      maintaining PCI DSS compliance.
  - name: tokens_management
    description: Manage stored Commerce tokens including CVC2 security code management.
  - name: compliance_service
    description: >-
      Safely handle sensitive cardholder data while maintaining PCI DSS
      compliance via a secure proxy service.
  - name: network_tokens
    description: >-
      Manage network tokens with major card schemes with automatic lifecycle
      management.
  - name: merchants
    description: >-
      Configure and manage merchant accounts based on your chosen operating
      model.
  - name: reconciliation
    description: Reconcile imported token data.
  - name: processor_backup
    description: >-
      Migrate payment tokens from third-party processors (currently supports
      stripe.com).
paths:
  /authentications:
    get:
      tags:
        - authentications_data
      summary: Get authentications
      description: >
        Get a list of all the authentications for this account.

        The results are grouped into pages. The caller can specify how many
        customers per page shall be listed (maximum is 500).
      operationId: get_authentications
      parameters:
        - in: query
          name: type
          description: Parameter to filter the authentication types
          schema:
            type: string
          required: false
        - in: query
          name: limit
          description: >
            The desired amount of records per page. The parameter defaults to 50
            if it is omitted and has a maximum of 500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 1
          required: false
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationList'
              example:
                data:
                  - id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                    amount: 1000
                    currency_code: EUR
                    action_requirement:
                      type: use_sdk
                      session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                    created_at: '2023-10-10T00:00:00Z'
                    challenge_preference: CHALLENGE
                    purchase_date: '20241010000000'
                    use_case: ONE_OFF
                    source:
                      type: token
                      token_id: 71820e49-6822-4df1-8db5-d245456172b6
                    status: PROCESSING
                pagination:
                  current_page: 1
                  page_size: 1
                  total_items: 1
                  total_pages: 1
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      security:
        - APIKeyAuth: []
components:
  schemas:
    AuthenticationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Authentication'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Authentication:
      type: object
      properties:
        id:
          type: string
          description: The ID of the authentication
          format: uuid
        action_requirement:
          $ref: '#/components/schemas/ActionRequirement'
        amount:
          $ref: '#/components/schemas/Amount'
        authentication_result:
          $ref: '#/components/schemas/AuthenticationResult'
        challenge_preference:
          type: string
          description: |
            The preference with respect to an eventual challenge.

            There is no guarantee that the preference can be fulfilled.
          default: CHALLENGE
          enum:
            - CHALLENGE
            - NO_PREFERENCE
            - NO_CHALLENGE
        created_at:
          type: string
          description: The date-time the authentication was created (following ISO 8601)
          format: datetime
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        recurring_expiry:
          type: string
          description: |
            The date when the latest subsequent authentication can happen.
            Requires the format `yyyyMMdd`.
        recurring_frequency:
          type: integer
          description: Indicates the minimum number of days between authentications.
        failure_details:
          type: array
          description: >
            The reasons why an authentication failed during processing in
            Commerce.
          items:
            type: object
            properties:
              classifier:
                type: string
              message:
                type: string
            required:
              - classifier
              - message
        finished_at:
          type: string
          description: The date-time the authentication was finished (following ISO 8601)
          format: datetime
        original_authentication:
          type: string
          format: uuid
          description: >
            The ID of the original authentication in case of subsequent
            authentications
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
        number_of_installments:
          type: integer
          description: >
            Indicates the maximum number of authorisations permitted for
            installment payments.
        purchase_date:
          type: string
          description: |
            The data when the purchase was made. Requires the
            format `yyyyMMddHHmmss` and defaults to now.
        status:
          type: string
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
        source:
          $ref: '#/components/schemas/AuthenticationRequestSource'
        use_case:
          type: string
          enum:
            - ONE_OFF
            - INITIAL_RECURRING
            - INITIAL_INSTALLMENT
            - SUBSEQUENT_RECURRING
            - SUBSEQUENT_INSTALLMENT
      required:
        - amount
        - created_at
        - currency_code
        - id
        - status
        - source
        - use_case
    Pagination:
      type: object
      description: >
        The meta-data describing lists of data from the Commerce API. The pages
        are indexed from 1 up to the total_pages.
      properties:
        current_page:
          type: integer
          description: The index of the current page
        page_size:
          type: integer
          description: >
            The maximum number of items on a page (relates to the limit query
            parameter)
        total_items:
          type: integer
          description: The total quantity of items regardless of the pages
        total_pages:
          type: integer
          description: The total amount of pages the data is segmented into
      example:
        current_page: 1
        page_size: 1
        total_items: 1
        total_pages: 1
    ErrorGeneric:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
    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
    ActionRequirement:
      type: object
      properties:
        type:
          type: string
          enum:
            - use_sdk
        session_id:
          type: string
          format: uuid
          description: The id of the session to use for the SDK
      required:
        - type
        - session_id
    Amount:
      type: integer
      minimum: 0
      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.
    AuthenticationResult:
      type: object
      description: >
        The final result of the authentication.

        It holds in the cardholder authentication data (CAVV) and if there is a
        network token present, the token authentication data (TAVV).
      properties:
        cardholder_data:
          type: object
          description: The CAVV from the 3-D Secure authentication.
          properties:
            authentication_value:
              type: string
            ds_transaction_id:
              type: string
            eci:
              type: string
            acs_transaction_id:
              type: string
            challenge_cancel_reason:
              type: string
            status:
              type: string
            status_reason_code:
              type: string
            version:
              type: string
          required:
            - authentication_value
            - ds_transaction_id
            - eci
        encrypted_token_data:
          $ref: '#/components/schemas/EncryptedAuthenticationData'
    CurrencyCode:
      type: string
      description: |
        The three letter currency code.
        See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)
    AuthenticationRequestSource:
      description: >
        The payment credentials for this authentication request.


        | Type  |
        Description                                                     |

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

        | token | An already existing Commerce token can be used as source for
        the authentication. |
      discriminator:
        propertyName: type
        mapping:
          token:
            $ref: '#/components/schemas/RequestSourceToken-2'
      default: token
      oneOf:
        - $ref: '#/components/schemas/RequestSourceToken-2'
    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
    EncryptedAuthenticationData:
      type: string
      description: >
        JWE encrypted JSON string containing authentication data.


        Encrypted in a symmetric way with the shared encryption key using
        "alg"=A256GCMKW and "enc"="A256GCM". 

        For decryption make sure the shared secret is hashed with a sha256
        digest.


        The decrypted JSON has the following format:


        ```json

        {
            network_token: {
              token: "token_value",
              expiry_year: 2023,
              expiry_month: 12
            },
            cryptogram: "cryptogram_value",
            eci: "eci_value"
        }

        ```

        - The field `network_token` contains the value of the token, the year of
        expiry and the month of expiry of the token and is always included.


        - The field `cryptogram` contains the value of the cryptogram and is
        always included.


        - The field `eci` can instead have a value if there was an Electronic
        Commerce Indicator assigned, or it can be `null` if no information was
        provided.
    RequestSourceToken-2:
      type: object
      properties:
        type:
          type: string
        token_id:
          type: string
          format: uuid
      required:
        - type
        - token_id
  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
    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
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header

````