openapi: 3.2.0
info:
  title: Gr4vy Vault Forward Configurations API
  version: 1.1.0-beta
  contact:
    name: Gr4vy Support
    email: code@gr4vy.com
    url: https://gr4vy.com
  termsOfService: https://gr4vy.com
  license:
    name: MIT
    url: https://raw.githubusercontent.com/gr4vy/gr4vy-openapi/main/LICENSE
  description: 'Welcome to the Gr4vy API reference documentation.

    Our API is still very much a work in product and subject to change.'
servers:
- url: https://api.sandbox.{id}.gr4vy.app
  x-speakeasy-server-id: sandbox
  variables:
    id:
      default: example
      description: The subdomain for your Gr4vy instance.
- url: https://api.{id}.gr4vy.app
  x-speakeasy-server-id: production
  variables:
    id:
      default: example
      description: The subdomain for your Gr4vy instance.
security:
- bearerAuth: []
tags:
- name: Vault Forward Configurations
  description: 'A Vault Forward Configuration represents a third party service that is

    currently enabled to send requests containing PCI data.'
paths:
  /vault-forward/configs:
    get:
      operationId: list-vault-forward-config
      summary: List configured Vault Forward endpoints
      description: 'Lists the currently configured Vault Forward endpoints that can be used to forward

        PCI data to.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      parameters:
      - schema:
          type: integer
          default: 20
          example: 1
          minimum: 1
          maximum: 100
          format: int32
        in: query
        name: limit
        description: Defines the maximum number of items to return for this request.
      - schema:
          type: string
          format: ''
          example: ZXhhbXBsZTE
        in: query
        name: cursor
        description: 'A cursor that identifies the page of results to return. This is used to

          paginate the results of this API.


          For the first page of results, this parameter can be left out.

          For additional pages, use the value returned by the API in

          the `next_cursor` field. Similarly the `previous_cursor` can be used to

          reverse backwards in the list.'
      responses:
        '200':
          description: Returns a list of Vault Forward configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfigs'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
    post:
      summary: Enable new Vault Forward endpoint
      operationId: new-vault-forward-config
      description: 'Enables a new Vault Forward endpoint. This allows this endpoint

        to be used to forward PCI data to. Only 1 configuration may

        exist at a time for a given definition.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PCIForwardConfigRequest'
      responses:
        '201':
          description: Returns the created Vault Forward configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfig'
        '400':
          description: Returns an error if the request was badly formatted or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400BadRequest'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '409':
          description: Returns an error if there is an attempt to create multiple configurations for the same definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409DuplicateRecord'
  /vault-forward/configs/{config_id}:
    parameters:
    - schema:
        type: string
        example: 46973e9d-88a7-44a6-abfe-be4ff0134ff4
        format: uuid
      name: config_id
      in: path
      required: true
      description: The ID of the Vault Forward configuration.
    get:
      operationId: get-vault-forward-config
      summary: Get configured Vault Forward endpoints
      description: 'Gets a configured Vault Forward endpoints that can be used to forward

        PCI data to.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      responses:
        '200':
          description: Returns the Vault Forward configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfig'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
    delete:
      operationId: delete-vault-forward-config
      summary: Remove a configured Vault Forward endpoint
      description: 'Removes a previously configured Vault Forward endpoint, effectively disallowing

        data to be sent to this endpoint.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      responses:
        '204':
          description: Returns an empty response.
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
  /vault-forward/configs/{config_id}/authentications:
    parameters:
    - schema:
        type: string
        example: 46973e9d-88a7-44a6-abfe-be4ff0134ff4
        format: uuid
      name: config_id
      in: path
      required: true
      description: The ID of the Vault Forward configuration.
    get:
      operationId: list-vault-forward-config-authentication
      summary: List configured Vault Forward authentication methods
      description: 'Lists the configured Vault Forward authentication methods that can

        be applied in Vault Forward requests for the given configuration.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      responses:
        '200':
          description: Returns a list of Vault Forward authentication methods.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfigAuthentications'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
    post:
      operationId: add-vault-forward-config-authentication
      summary: Adds new Vault Forward authentication method
      description: 'Configures a new Vault Forward authentication method. This allows the

        authentication method to be be applied in Vault Forward requests.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PCIForwardConfigAuthenticationRequest'
      responses:
        '201':
          description: Returns the created Vault Forward authentication method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfigAuthentication'
        '400':
          description: Returns an error if the request was badly formatted or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400BadRequest'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
  /vault-forward/configs/{config_id}/authentications/{authentication_id}:
    parameters:
    - schema:
        type: string
        example: 46973e9d-88a7-44a6-abfe-be4ff0134ff4
        format: uuid
      name: config_id
      in: path
      required: true
      description: The ID of the Vault Forward configuration.
    - schema:
        type: string
        example: 46973e9d-88a7-44a6-abfe-be4ff0134ff4
        format: uuid
      name: authentication_id
      in: path
      required: true
      description: The ID of the Vault Forward authentication method.
    get:
      operationId: get-vault-forward-config-authentication
      summary: Get Vault Forward authentication method
      description: Gets a configured Vault Forward authentication method.
      tags:
      - Vault Forward Configurations
      x-internal: true
      responses:
        '200':
          description: Returns the Vault Forward authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfigAuthentication'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
    put:
      operationId: update-vault-forward-config-authentication
      summary: Update Vault Forward authentication method
      description: Updates an existing Vault Forward authentication method.
      tags:
      - Vault Forward Configurations
      x-internal: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PCIForwardConfigAuthenticationUpdate'
      responses:
        '200':
          description: Returns the updated Vault Forward authentication method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PCIForwardConfigAuthentication'
        '400':
          description: Returns an error if the request was badly formatted or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400BadRequest'
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
    delete:
      operationId: delete-vault-forward-config-authentication
      summary: Remove a Vault Forward authentication method
      description: 'Removes a configured Vault Forward authentication method,

        disallowing it from being applied in Vault Forward requests.'
      tags:
      - Vault Forward Configurations
      x-internal: true
      responses:
        '204':
          description: Returns an empty response.
        '401':
          description: Returns an error if no valid authentication was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401Unauthorized'
        '404':
          description: Returns an error if the resource can not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404NotFound'
components:
  schemas:
    PCIForwardConfigRequest:
      title: Vault Forward configuration (Create)
      type: object
      description: Request body to create a Vault Forward configuration.
      x-internal: true
      required:
      - definition_id
      properties:
        definition_id:
          type: string
          description: The ID of the Vault Forward definition to configure.
          example: amadeus
    PCIForwardConfigAuthenticationRequest:
      title: Vault Forward authentication method (Create)
      type: object
      description: Request body to create a Vault Forward authentication method.
      x-internal: true
      x-tags:
      - Request Bodies
      required:
      - kind
      - display_name
      - fields
      properties:
        kind:
          type: string
          description: 'The kind of authentication to be used in a Vault Forward request.

            '
          enum:
          - mle
          - mtls
          - signature
          example: mle
        display_name:
          type: string
          description: A custom name for the authentication method. This will be shown in the Admin UI.
          example: My Message Level Encryption
          minLength: 1
          maxLength: 50
        fields:
          type: array
          description: 'A list of fields, each containing a key-value pair for each field defined

            by the definition for this authentication method.'
          items:
            type: object
            description: 'A key-value pair that represents a field defined in the definition for

              this authentication method.'
            required:
            - key
            - value
            properties:
              key:
                type: string
                description: The key of the field to set a value for.
                example: private_key
                minLength: 1
                maxLength: 50
              value:
                type: string
                description: The value of a field to set.
                example: REDACTED_STRIPE_KEY
                minLength: 0
                maxLength: 5000
    Error404NotFound:
      title: Not Found Error
      type: object
      description: Not Found Error (HTTP 404).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: The reason code for the error.
          example: not_found
          enum:
          - not_found
          - pending_creation
        status:
          type: integer
          description: '`404`.'
          example: 404
          enum:
          - 404
        message:
          type: string
          description: The human readable reason for the error.
          example: The resource could not be found
        details:
          type: array
          description: 'A list of detail objects that further clarify the reason for the error.

            Not every error supports more detail.'
          example: []
          items:
            $ref: '#/components/schemas/ErrorDetail'
    PCIForwardConfigAuthentications:
      title: Vault Forward authentication methods
      type: object
      description: A list of configured Vault Forward authentication methods.
      x-internal: true
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PCIForwardConfigAuthentication'
    PCIForwardConfigs:
      title: Vault Forward configurations
      type: object
      description: A list of available Vault Forward configurations.
      x-internal: true
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PCIForwardConfig'
        limit:
          type: integer
          description: 'The limit applied to request. This represents the number of items that are at

            maximum returned by this request.'
          format: int32
          minimum: 1
          maximum: 100
          example: 1
          default: 20
        next_cursor:
          type:
          - string
          - 'null'
          description: 'The cursor that represents the next page of results. Use the `cursor` query

            parameter to fetch this page of items.'
          example: ZXhhbXBsZTE
          minLength: 1
          maxLength: 1000
        previous_cursor:
          type:
          - string
          - 'null'
          description: 'The cursor that represents the next page of results. Use the `cursor` query

            parameter to fetch this page of items.'
          example: null
          minLength: 1
          maxLength: 1000
    ErrorDetail:
      title: Error details
      description: Additional detail about the part of a request body that caused an issue.
      type: object
      x-tags:
      - Errors
      properties:
        location:
          type: string
          example: body
          description: The location where the error caused an issue.
          enum:
          - query
          - body
          - path
          - header
        type:
          type: string
          example: value_error.missing
          description: A unique identifier for the type of error that occurred.
        pointer:
          type: string
          example: /payment_method/number
          description: 'The exact item for which the validation did not succeed. This is a JSON

            pointer for request bodies, while for query, path, and header parameters

            it is the name of the parameter.'
        message:
          type: string
          example: field required
          description: A human readable message for this error detail.
    PCIForwardConfig:
      title: A Vault Forward configuration
      type: object
      description: A configured Vault Forward configuration.
      x-internal: true
      properties:
        type:
          type: string
          description: The type of this resource. It is always `vault-forward-config`.
          default: vault-forward-config
          example: vault-forward-config
        id:
          type: string
          format: uuid
          description: The ID of this Vault Forward configuration.
          example: faaad066-30b4-4997-a438-242b0752d7e1
        created_at:
          type: string
          format: date-time
          example: '2012-12-12T10:53:43+00:00'
          description: The date and time when this configuration was created.
        updated_at:
          type: string
          format: date-time
          example: '2012-12-12T10:53:43+00:00'
          description: The date and time when this configuration was last updated.
        merchant_account_id:
          type: string
          description: The unique ID for a merchant account.
          example: default
        definition_id:
          type: string
          description: The ID of the Vault Forward definition.
          example: amadeus
        display_name:
          type: string
          description: The display name for this configuration.
          example: Amadeus
        hosts:
          type: array
          description: The hosts where Vault Forward requests are allowed for this definition.
          minItems: 1
          items:
            type: string
          example:
          - https://api.amadeus.com
          - https://test.api.amadeus.com
        authentications:
          type: array
          description: Authentication methods that can be applied in Vault Forward requests.
          minItems: 0
          items:
            $ref: '#/components/schemas/PCIForwardConfigAuthentication'
        creator:
          type:
          - object
          - 'null'
          description: The user who created the Vault Forward configuration.
          properties:
            id:
              type: string
              format: uuid
              description: The ID of the user.
              example: 77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5
            name:
              type: string
              description: The name of the user.
              example: John L
            email_address:
              type: string
              description: The email address for this user.
              example: john@example.com
    PCIForwardConfigAuthenticationUpdate:
      title: Vault Forward authentication method (Update)
      type: object
      description: Request body to update a Vault Forward authentication method.
      x-internal: true
      x-tags:
      - Request Bodies
      properties:
        display_name:
          type: string
          description: A custom name for the authentication method. This will be shown in the Admin UI.
          example: My Message Level Encryption
          minLength: 1
          maxLength: 50
        fields:
          type: array
          description: 'A list of fields, each containing a key-value pair for each field defined

            by the definition for this authentication method.'
          items:
            type: object
            description: 'A key-value pair that represents a field defined in the definition for

              this authentication method.'
            required:
            - key
            - value
            properties:
              key:
                type: string
                description: The key of the field to set a value for.
                example: private_key
                minLength: 1
                maxLength: 50
              value:
                type: string
                description: 'The value of a field to set; you can unset optional fields by

                  setting this to an empty string `""`.'
                example: REDACTED_STRIPE_KEY
                minLength: 0
                maxLength: 5000
    Error409DuplicateRecord:
      title: Duplicate Record Error
      type: object
      description: Duplicate Record Error (HTTP 409).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: '`duplicate_record`.'
          example: duplicate_record
          enum:
          - duplicate_record
        status:
          type: integer
          description: '`409`.'
          example: 409
          enum:
          - 409
        message:
          type: string
          description: Further details on the field that triggered the error.
          example: A duplicate record exists with this external_identifier value
        details:
          type: array
          description: 'A list of detail objects that further clarify the reason for the error.

            Not every error supports more detail.'
          example: []
          items:
            $ref: '#/components/schemas/ErrorDetail'
    Error401Unauthorized:
      title: Unauthorized Error
      type: object
      description: Unauthorized Error (HTTP 401).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: '`unauthorized`.'
          example: unauthorized
          enum:
          - unauthorized
        status:
          type: integer
          description: '`401`.'
          example: 401
          enum:
          - 401
        message:
          type: string
          description: No valid API authentication found.
          example: No valid API authentication found
          enum:
          - No valid API authentication found
        details:
          type: array
          description: 'A list of detail objects that further clarify the reason for the error.

            Not every error supports more detail.'
          example: []
          items:
            $ref: '#/components/schemas/ErrorDetail'
    PCIForwardConfigAuthentication:
      title: A Vault Forward authentication method
      type: object
      description: A configured Vault Forward authentication method.
      x-internal: true
      properties:
        type:
          type: string
          description: The type of this resource. It is always `vault-forward-config-authentication`.
          default: vault-forward-config-authentication
          example: vault-forward-config-authentication
        id:
          type: string
          format: uuid
          description: The ID of this Vault Forward authentication method.
          example: faaad066-30b4-4997-a438-242b0752d7e1
        created_at:
          type: string
          format: date-time
          example: '2012-12-12T10:53:43+00:00'
          description: The date and time when this configuration was created.
        updated_at:
          type: string
          format: date-time
          example: '2012-12-12T10:53:43+00:00'
          description: The date and time when this configuration was last updated.
        kind:
          type: string
          description: 'The kind of authentication to be used in a Vault Forward request.

            '
          enum:
          - mle
          - mtls
          - signature
          example: mle
        label:
          type: string
          description: A label that describes this authentication method.
          example: My MLE
        display_name:
          type: string
          description: The display name for this authentication method given when created.
          example: My MLE
        fields:
          type: array
          description: 'A list of fields, each containing a key-value pair for each field

            configured for this authentication method. Fields marked as `secret`

            are not returned.'
          items:
            type: object
            properties:
              key:
                type: string
                minLength: 1
                maxLength: 50
                description: The key of the field.
                example: secret_key
              value:
                type: string
                minLength: 1
                maxLength: 5000
                description: The value of the field.
                example: REDACTED_STRIPE_KEY
        creator:
          type:
          - object
          - 'null'
          description: The user who created the Vault Forward authentication method.
          properties:
            id:
              type: string
              format: uuid
              description: The ID of the user.
              example: 77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5
            name:
              type: string
              description: The name of the user.
              example: John L
            email_address:
              type: string
              description: The email address for this user.
              example: john@example.com
    Error400BadRequest:
      title: Bad Request
      type: object
      description: Bad Request (HTTP 400).
      x-tags:
      - Errors
      properties:
        type:
          type: string
          description: '`error`.'
          enum:
          - error
          example: error
        code:
          type: string
          description: A short code that describes the reason for the error.
          example: bad_request
          enum:
          - bad_request
          - incorrect_json
          - invalid_credentials
        status:
          type: integer
          description: '`400`.'
          example: 400
          enum:
          - 400
        message:
          type: string
          description: A human-readable reason for the error.
          example: Missing '****' field
        details:
          type: array
          description: A list of detail objects that further clarify the reason for the error.
          items:
            $ref: '#/components/schemas/ErrorDetail'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT