openapi: 3.0.1
info:
  title: Very Good Security (VGS) API
  description: >-
    Specification of the public Very Good Security (VGS) APIs. Covers the VGS
    Vault HTTP API for tokenization (create / reveal / update / delete aliases)
    served from the verygoodvault.com hosts with HTTP Basic authentication, and
    the VGS Accounts (control plane) API for managing organizations, vaults, and
    routes served from accounts.apps.verygoodsecurity.com with a Bearer access
    token obtained via the OAuth2 client-credentials flow. Endpoint shapes for
    the Vault API mirror the published VGS Vault API reference; Accounts
    resources are modeled from VGS platform / IAM documentation.
  termsOfService: https://www.verygoodsecurity.com/terms
  contact:
    name: VGS Support
    email: support@verygoodsecurity.com
  version: '1.0'
servers:
  - url: https://api.sandbox.verygoodvault.com
    description: Vault API - Sandbox
  - url: https://api.live.verygoodvault.com
    description: Vault API - Live
  - url: https://api.live-eu-1.verygoodvault.com
    description: Vault API - Live EU
  - url: https://accounts.apps.verygoodsecurity.com
    description: Accounts (control plane) API
tags:
  - name: aliases
    description: Tokenization operations on the VGS Vault HTTP API.
  - name: organizations
    description: Organization resources on the VGS Accounts API.
  - name: vaults
    description: Vault resources on the VGS Accounts API.
  - name: routes
    description: Inbound / outbound proxy route resources on the VGS Accounts API.
paths:
  /aliases:
    post:
      operationId: createAliases
      tags:
        - aliases
      summary: Create aliases
      description: >-
        Stores multiple values at once and returns their aliases. May also be
        used to associate additional (secondary) aliases with the same
        underlying data as a reference alias. You cannot reference the same
        alias more than once in a single request.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAliasesRequest'
            examples:
              createNew:
                summary: Create a new alias
                value:
                  data:
                    - value: '122105155'
                      classifiers:
                        - bank-account
                      format: UUID
                      storage: PERSISTENT
              reference:
                summary: Reference an existing alias
                value:
                  data:
                    - alias: tok_sandbox_bhtsCwFUzoJMw9rWUfEV5e
                      format: RAW_UUID
                      storage: PERSISTENT
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: List of stored values along with their aliases.
                    items:
                      $ref: '#/components/schemas/RevealedData'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    get:
      operationId: revealMultipleAliases
      tags:
        - aliases
      summary: Reveal multiple aliases
      description: >-
        Given a list of aliases, retrieves all associated values stored in the
        vault. This endpoint may expose sensitive data and is disabled by
        default; contact VGS to enable it.
      security:
        - basicAuth: []
      parameters:
        - name: q
          in: query
          required: true
          description: Comma-separated list of aliases to reveal.
          schema:
            type: string
          example: tok_sandbox_5UpnbMvaihRuRwz5QXwBFw,tok_sandbox_9ToiJHedw1nE1Jfx1qYYgz
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/RevealedData'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /aliases/{alias}:
    parameters:
      - $ref: '#/components/parameters/alias'
    get:
      operationId: revealAlias
      tags:
        - aliases
      summary: Reveal single alias
      description: >-
        Retrieves a stored value along with its aliases. This endpoint may
        expose sensitive data and is disabled by default; contact VGS to enable
        it.
      security:
        - basicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      $ref: '#/components/schemas/RevealedData'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    put:
      operationId: updateAlias
      tags:
        - aliases
      summary: Update data classifiers
      description: Apply new classifiers to the value the specified alias is associated with.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAliasRequest'
      responses:
        '204':
          description: No Content
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    delete:
      operationId: deleteAlias
      tags:
        - aliases
      summary: Delete alias
      description: Removes a single alias.
      security:
        - basicAuth: []
      responses:
        '204':
          description: No Content
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /organizations:
    get:
      operationId: listOrganizations
      tags:
        - organizations
      summary: List organizations
      description: >-
        Reads basic organization details accessible to the authenticated
        service account (requires the organizations:read scope). Served from the
        VGS Accounts control plane.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /organizations/{organizationId}:
    parameters:
      - $ref: '#/components/parameters/organizationId'
    get:
      operationId: getOrganization
      tags:
        - organizations
      summary: Get organization
      description: Retrieves a single organization by identifier (organizations:read scope).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /vaults:
    get:
      operationId: listVaults
      tags:
        - vaults
      summary: List vaults
      description: >-
        Lists the vaults in the organization, including name and identifier
        (requires the vaults:read scope).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    post:
      operationId: createVault
      tags:
        - vaults
      summary: Create vault
      description: Creates a new vault in the organization (requires the vaults:write scope).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultCreateRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /vaults/{vaultId}:
    parameters:
      - $ref: '#/components/parameters/vaultId'
    get:
      operationId: getVault
      tags:
        - vaults
      summary: Get vault
      description: Retrieves a single vault by identifier (vaults:read scope).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /vaults/{vaultId}/routes:
    parameters:
      - $ref: '#/components/parameters/vaultId'
    get:
      operationId: listRoutes
      tags:
        - routes
      summary: List routes
      description: >-
        Lists inbound and outbound proxy routes configured on the vault
        (requires the routes:read scope).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Route'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    post:
      operationId: createRoute
      tags:
        - routes
      summary: Create route
      description: >-
        Creates an inbound (reverse) or outbound (forward) proxy route on the
        vault that redacts or reveals sensitive data in transit (requires the
        routes:write scope).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Route'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
  /vaults/{vaultId}/routes/{routeId}:
    parameters:
      - $ref: '#/components/parameters/vaultId'
      - $ref: '#/components/parameters/routeId'
    get:
      operationId: getRoute
      tags:
        - routes
      summary: Get route
      description: Retrieves a single route by identifier (routes:read scope).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    put:
      operationId: updateRoute
      tags:
        - routes
      summary: Update route
      description: Replaces a route configuration on the vault (routes:write scope).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Route'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
    delete:
      operationId: deleteRoute
      tags:
        - routes
      summary: Delete route
      description: Removes a route from the vault (routes:write scope).
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No Content
        default:
          $ref: '#/components/responses/ApiErrorsResponse'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication used by the VGS Vault HTTP API. Username and
        password are the vault access credentials generated in the VGS
        dashboard.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer access token used by the VGS Accounts API. Obtain the token from
        the OAuth2 client-credentials endpoint at
        https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token
        using a service-account client id and secret, then pass it as
        Authorization: Bearer <token>.
  parameters:
    alias:
      name: alias
      in: path
      required: true
      description: Alias to operate on.
      schema:
        type: string
      example: tok_sandbox_bhtsCwFUzoJMw9rWUfEV5e
    organizationId:
      name: organizationId
      in: path
      required: true
      description: Organization identifier.
      schema:
        type: string
    vaultId:
      name: vaultId
      in: path
      required: true
      description: Vault identifier.
      schema:
        type: string
      example: tntabcdefg
    routeId:
      name: routeId
      in: path
      required: true
      description: Route identifier.
      schema:
        type: string
  responses:
    ApiErrorsResponse:
      description: Something went wrong
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                minItems: 1
                items:
                  $ref: '#/components/schemas/ApiError'
  schemas:
    ApiError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
        title:
          type: string
          description: High-level reason of why the request failed.
        detail:
          type: string
          description: Explanation of what exactly went wrong.
        href:
          type: string
          description: Request URL.
    AliasFormat:
      type: string
      description: Format of the generated alias string.
      enum:
        - FPE_ACC_NUM_T_FOUR
        - FPE_ALPHANUMERIC_ACC_NUM_T_FOUR
        - FPE_SIX_T_FOUR
        - FPE_SSN_T_FOUR
        - FPE_T_FOUR
        - NUM_LENGTH_PRESERVING
        - PFPT
        - RAW_UUID
        - UUID
      example: UUID
    Alias:
      type: object
      properties:
        alias:
          type: string
          description: Opaque string used to substitute the raw value.
          example: tok_sandbox_bhtsCwFUzoJMw9rWUfEV5e
        format:
          $ref: '#/components/schemas/AliasFormat'
    RevealedData:
      type: object
      properties:
        value:
          type: string
          description: Decrypted value stored in the vault.
          example: '122105155'
        classifiers:
          type: array
          description: List of tags the value is classified with.
          items:
            type: string
          example:
            - bank-account
        aliases:
          type: array
          description: List of aliases associated with the value.
          items:
            $ref: '#/components/schemas/Alias'
        created_at:
          type: string
          format: date-time
          description: Creation time, in UTC.
          example: '2019-05-15T12:30:45Z'
        storage:
          type: string
          enum:
            - PERSISTENT
            - VOLATILE
          default: PERSISTENT
          description: >-
            Storage medium. VOLATILE persists data in an in-memory store for one
            hour, required for PCI-compliant storage of card security codes.
    CreateAliasesRequestNew:
      type: object
      required:
        - value
        - format
      properties:
        value:
          type: string
          description: Raw value to encrypt and store in the vault.
          example: '122105155'
        classifiers:
          type: array
          description: List of tags to classify the value with.
          items:
            type: string
          example:
            - bank-account
        format:
          $ref: '#/components/schemas/AliasFormat'
        storage:
          type: string
          enum:
            - PERSISTENT
            - VOLATILE
          default: PERSISTENT
          description: Storage medium to use.
    CreateAliasesRequestReference:
      type: object
      required:
        - alias
        - format
      properties:
        alias:
          type: string
          description: Existing alias to use as a reference.
          example: tok_sandbox_bhtsCwFUzoJMw9rWUfEV5e
        format:
          $ref: '#/components/schemas/AliasFormat'
    CreateAliasesRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          minItems: 1
          maxItems: 20
          items:
            oneOf:
              - $ref: '#/components/schemas/CreateAliasesRequestNew'
              - $ref: '#/components/schemas/CreateAliasesRequestReference'
    UpdateAliasRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - classifiers
          properties:
            classifiers:
              type: array
              description: List of tags to classify the value with.
              items:
                type: string
              example:
                - credit-cards
                - PII
    Organization:
      type: object
      properties:
        id:
          type: string
          description: Organization identifier.
        name:
          type: string
          description: Organization name.
        type:
          type: string
          description: Resource type.
          example: organizations
    Vault:
      type: object
      properties:
        id:
          type: string
          description: Vault identifier (tenant id).
          example: tntabcdefg
        name:
          type: string
          description: Human-readable vault name.
        environment:
          type: string
          enum:
            - SANDBOX
            - LIVE
          description: Vault environment.
        organization_id:
          type: string
          description: Owning organization identifier.
    VaultCreateRequest:
      type: object
      required:
        - name
        - environment
      properties:
        name:
          type: string
          description: Human-readable vault name.
        environment:
          type: string
          enum:
            - SANDBOX
            - LIVE
          description: Vault environment to create.
        organization_id:
          type: string
          description: Owning organization identifier.
    Route:
      type: object
      properties:
        id:
          type: string
          description: Route identifier.
        type:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
          description: >-
            INBOUND (reverse) proxy routes sit between clients and your server;
            OUTBOUND (forward) proxy routes sit between your server and third
            parties.
        protocol:
          type: string
          enum:
            - HTTP
          description: Proxy protocol.
        host_endpoint:
          type: string
          description: Upstream host pattern the route applies to.
        tags:
          type: object
          additionalProperties:
            type: string
          description: Arbitrary tags applied to the route.