swagger: '2.0'
info:
  version: 1.4.1
  title: Luna Cloud HSM Google Marketplace Service API
host: thales.<region>.market.dpondemand.io
schemes:
  - https
produces:
  - application/json
## these are the standard roles that the DPoD platform provides. the methods below will be tagged with
## the roles that are allowed to execute them. currently the permissions checks in the code are not
## automatically created by the code generator, so be sure to add them manually.
securityDefinitions:
  OAuth2:
    type: oauth2
    tokenUrl: /oauth/token
    flow: application
    scopes:
      dpod.operator: Thales Operator API credentials.
      dpod.service_account: Service account to create root admin user for automatic onboarding flow.
      dpod.slingshot_service_account: Slingshot Service account for external marketplaces.
      dpod.maestro_service_account: Maestro Service account for retrieving usage reports.
      dpod.client_prov_workflow_service_account: Client prov workflow Service account.
      dpod.tenant.spadmin: Service Provider Administrator user role. Used to access the user interface.
      dpod.tenant.admin: Tenant Administrator user role. Used to access the user interface.
      dpod.tenant.appowner: Application Owner user role. Used to access the user interface.
      dpod.tenant.api_spadmin: Service Provider Administrator API role. Used for application authentication over the API, the API role provides a subset of dpod.tenant.spadmin permissions to an application.
      dpod.tenant.api_appowner: Tenant Administrator and Application Owner API role. Used for application authentication over the API, the API role provides a subset of dpod.tenant.appowner and dpod.tenant.admin permissions to an application.
      dpod.tenant.api_service: Service API role. Used for application authentication over the API, the API role provides a subset of dpod.tenant.appowner and dpod.tenant.admin permissions to an application.
      dpod.osb-platform: OSB Platform client credentials
# add any paths and definitions that are not covered by the Open Service Broker spec here.consumes:
# for example, the parameters sent in a Service create operation may be serialized/deserialized as
# an object defined here
paths:
  /v2/service_instances/{instance_id}/service_bindings/{binding_id}/bundle:
    put:
      summary: Create a Client zip bundle using service binding details
      tags:
        - Bundle
      description: |
        Create a Client zip bundle from the user provided service binding details.
        The bundle contains configuration files, certificates, and Linux and Windows binaries for connecting to a Luna Cloud HSM.
      operationId: generateClient
      produces:
        - application/zip
        - application/octet-stream
        - application/json
      parameters:
        - name: instance_id
          in: path
          required: true
          type: string
          description: An OSB service instance id for a service in your tenant.
          minLength: 1
          maxLength: 255
        - name: binding_id
          in: path
          required: true
          type: string
          description: An OSB service binding id for a Client bound to a service in your tenant.
          minLength: 1
          maxLength: 255
        - name: HsmServiceBindingCredentials
          in: body
          description: Input parameters for Client zip bundle generation.
          schema:
            $ref: '#/definitions/HsmServiceBindingCredentials'
      responses:
        "200":
          description: Returns a Client zip bundle bound to a Luna Cloud HSM service partition.
          schema:
            type: file
      security:
        - OAuth2: [dpod.tenant.appowner, dpod.tenant.api_appowner, dpod.tenant.api_service, dpod.service_account, dpod.osb-platform]
  /v1/bundle:
    post:
      summary: Create a Client zip bundle using a Client ID and Client secret
      tags:
        - Bundle
      description: |
        Create a Client zip bundle using a Client ID and Client secret.
        The Client zip bundle contains Linux and Windows binaries.
        The bundle contains configuration files, certificates, and binaries for connecting to a Luna Cloud HSM.
      operationId: bundleClient
      produces:
        - application/zip
        - application/octet-stream
      parameters:
        - name: request
          in: body
          schema:
            $ref: '#/definitions/BundleCreationRequest'
      responses:
        "200":
          description: Returns a Client zip bundle that may be configured to access a Luna Cloud HSM service.
          schema:
            type: file
      security:
        - OAuth2: []
  /v1/info:
    get:
      summary: Return the DPoD Tenant login page for the service
      tags:
        - Info
      description: |
        Returns the DPoD login page and tenant id associated with the service instance.
        The endpoint is only available for services which have a unique dashboard instance.
      operationId: getInfo
      produces:
        - application/json
      parameters:
        - name: dashboard_id
          in: query
          required: true
          type: string
          minLength: 1
          maxLength: 255
      responses:
        "200":
          description: Returns the DPoD login page and tenant id associated with the service instance.
          schema:
            $ref: '#/definitions/Metadata'
  /v1/partitions:
    get:
      summary: Return available service partitions and partition details
      tags:
        - Partitions
      description: |
        Returns a list of all provisioned service partitions and associated partition details.
      operationId: listPartitions
      produces:
        - application/json
      responses:
        "200":
          description: Returns a list of partitions and partition details.
          schema:
            type: array
            items:
              $ref: '#/definitions/Partition'
      security:
        - OAuth2: []
    post:
      summary: Create a partition
      tags:
        - Partitions
      description: |
        Create a service partition.
        If not specified, the default partition deviceType is `cryptovisor`.
      operationId: createPartition
      produces:
        - application/json
      parameters:
        - name: partitionRequest
          in: body
          schema:
            $ref: '#/definitions/PartitionRequest'
      responses:
        "201":
          description: Partition was created.
          schema:
            $ref: '#/definitions/PartitionDetails'
          headers:
            Location:
              description: The path of the new partition.
              type: string
      security:
        - OAuth2: []
  /v1/partitions/{serialNumber}:
    get:
      summary: Return a partitions details
      tags:
        - Partitions
      description: |
        Returns the details of the specified partition.
      operationId: getPartition
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          type: string
          description: The partition unique identifier. Example - 1269045577436
          required: true
          minLength: 1
          maxLength: 255
      responses:
        "200":
          description: Returns the partition details.
          schema:
            $ref: '#/definitions/PartitionDetails'
      security:
        - OAuth2: []
    delete:
      summary: >
        Delete a partition

      tags:
        - Partitions
      description: |
        Delete a specific partition identified by its serial number.
        This operation is permanent and the partition cannot be recovered.
      operationId: deletePartition
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          type: string
          description: The partition unique identifier. Example - 1269045577436
          required: true
          minLength: 1
          maxLength: 255
      responses:
        "204":
          description: Partition was deleted.
      security:
        - OAuth2: []
    patch:
      summary: Update partition attributes
      tags:
        - Partitions
      description: |
        Update the specified partition attributes,
        such as the name of a specific partition.
      operationId: patchPartition
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          type: string
          description: The partition unique identifier. Example - 1269045577436
          required: true
          minLength: 1
          maxLength: 255
        - name: request
          in: body
          schema:
            $ref: '#/definitions/PartitionPatchRequest'
      responses:
        "200":
          description: Returns the updated partition details.
          schema:
            $ref: '#/definitions/PartitionDetails'
      security:
        - OAuth2: []
  /v1/partitions/{serialNumber}/clients:
    get:
      summary: Return a list of Clients bound to a partition
      tags:
        - Partitions
      description: |
        Returns a list of all Clients bound to a specific service partition.
      operationId: listClientsOfPartition
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          type: string
          description: The partition unique identifier. Example - 1269045577436
          required: true
          minLength: 1
          maxLength: 255
      responses:
        "200":
          description: Returns a list of all Clients that are bound to and can access this partition.
          schema:
            type: array
            items:
              $ref: '#/definitions/Client'
      security:
        - OAuth2: []
  /v1/partitions/{serialNumber}/snapshots:
    delete:
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          required: true
          type: string
          description: The partition unique identifier. Example - 1269045577436
          minLength: 1
          maxLength: 255
      responses:
        "204":
          description: Successful Response
        "403":
          description: Error response indicating the partition was not found, or the user has no permission
      security:
        - OAuth2: [dpod.tenant.appowner, dpod.tenant.api_appowner]
      tags:
        - Partitions
      description: |-
        Delete all snapshots of a partition
        :param serial: The serial of the partition
        :return:
      operationId: deleteSnapshots
      summary: Delete Snapshots
    get:
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          required: true
          type: string
          description: The partition unique identifier. Example - 1269045577436
          minLength: 1
          maxLength: 255
      responses:
        "200":
          description: Successful Response
          schema:
            $ref: './cv-api.yaml#/definitions/SnapshotList'
        "403":
          description: Error response indicating the partition was not found, or the user has no permission
      security:
        - OAuth2: [dpod.tenant.admin, dpod.tenant.appowner, dpod.tenant.api_appowner, dpod.tenant.api_service]
      tags:
        - Partitions
      description: |-
        Get a list of snapshots for a partition.
        :param serial: The serial of the partition
        :return: A list of snapshot metadata
      operationId: getSnapshots
      summary: Get Snapshots
    post:
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          required: true
          type: string
          description: The partition unique identifier. Example - 1269045577436
          minLength: 1
          maxLength: 255
        - in: body
          name: body
          required: true
          description: Contains information to create a partition snapshot
          schema:
            $ref: '#/definitions/SnapshotRequest'
      responses:
        "201":
          description: Successful Response
          schema:
            $ref: './cv-api.yaml#/definitions/SnapshotDefaultResponse'
        "400":
          description: Error response indicating the maximum limit of user snapshot creations has been reached
        "403":
          description: Error response indicating the partition was not found, or the user has no permission
      security:
        - OAuth2: [dpod.tenant.appowner, dpod.tenant.api_appowner, dpod.tenant.api_service]
      tags:
        - Partitions
      description: |-
        Take a snapshot of a partition.
        :param serial: The serial of the partition
        :param request_body: Optionally the TTL and the metadata for the snapshot
        :return: The timestamp of the created partition.
      operationId: createSnapshot
      summary: Create Snapshot
  /v1/partitions/{serialNumber}/snapshots/{timestamp}:
    delete:
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          required: true
          type: string
          description: The partition unique identifier. Example - 1269045577436
          minLength: 1
          maxLength: 255
        - name: timestamp
          in: path
          required: true
          type: integer
          format: int64
          minimum: 1
          maximum: 9999999999999
          description: The UNIX timestamp in milliseconds of the snapshot. Example - 1726258623946
      responses:
        "204":
          description: Successful Response
        "403":
          description: Error response indicating the partition or the snapshot with given timestamp were not found, or the user has no permission
      security:
        - OAuth2: [dpod.tenant.appowner, dpod.tenant.api_appowner]
      tags:
        - Partitions
      description: |-
        Delete a snapshot of a partition based on its timestamp
        :param timestamp: The time the snapshot was taken (in milliseconds UTC timestamp format)
        :param serial: The serial of the partition
        :return:
      operationId: deleteSnapshot
      summary: Delete Snapshot
    put:
      produces:
        - application/json
      parameters:
        - name: serialNumber
          in: path
          pattern: ^[0-9]+$
          description: The partition unique identifier. Example - 1269045577436
          required: true
          minLength: 1
          maxLength: 255
          type: string
        - name: timestamp
          in: path
          required: true
          type: integer
          format: int64
          minimum: 1
          maximum: 9999999999999
          description: The UNIX timestamp in milliseconds of the snapshot. Example - 1726258623946
      responses:
        "200":
          description: Successful Response
          schema:
            $ref: './cv-api.yaml#/definitions/SnapshotDefaultResponse'
        "403":
          description: Error response indicating the partition or the snapshot with given timestamp were not found, or the user has no permission
      security:
        - OAuth2: [dpod.tenant.appowner, dpod.tenant.api_appowner]
      tags:
        - Partitions
      description: |-
        Restore a snapshot for a partition based on its creation timestamp
        :param serial: The serial of the partition
        :param timestamp: The time the snapshot was taken (in milliseconds UTC timestamp format)
        :return:
      operationId: restoreSnapshot
      summary: Restore Snapshot
  /v1/grants:
    post:
      summary: Configure Client access to a partition
      tags:
        - Grants
      description: Allow or revoke a Client's access to a service partition.
      operationId: grantClient
      produces:
        - application/json
      parameters:
        - name: request
          in: body
          schema:
            $ref: '#/definitions/GrantRequest'
      responses:
        "200":
          description: Client access was updated.
      security:
        - OAuth2: []
  /v1/clients:
    get:
      summary: Return a list of available Clients
      tags:
        - Clients
      description: |
        Returns a list of all Clients which have been created for the service and associated partitions.
      operationId: listClients
      produces:
        - application/json
      responses:
        "200":
          description: Returns the list of available Clients.
          schema:
            type: array
            items:
              $ref: '#/definitions/Client'
      security:
        - OAuth2: []
    post:
      summary: Create a Client
      tags:
        - Clients
      description: |
        Create a Client bound to a specified partition.
      operationId: createClient
      produces:
        - application/json
      parameters:
        - name: partitionRequest
          in: body
          schema:
            $ref: '#/definitions/ClientRequest'
      responses:
        "201":
          description: Client was created.
          schema:
            $ref: '#/definitions/HsmServiceBindingCredentials'
          headers:
            Location:
              description: The path of the created Client resource.
              type: string
      security:
        - OAuth2: []
  /v1/clients/{clientId}:
    get:
      summary: Return Client details
      tags:
        - Clients
      description: Return the details of the specified Client.
      operationId: getClient
      produces:
        - application/json
      parameters:
        - name: clientId
          in: path
          type: string
          description: |
            The Client unique identifier.
            Example: caf85feb-21f7-41cc-8277-002b5b0942dc
          required: true
          minLength: 1
          maxLength: 255
      responses:
        "200":
          description: Returns the Client details.
          schema:
            $ref: '#/definitions/Client'
      security:
        - OAuth2: []
    delete:
      summary: Delete a Client
      tags:
        - Clients
      description: |
        Delete the specified client.
      operationId: deleteClient
      produces:
        - application/json
      parameters:
        - name: clientId
          in: path
          type: string
          description: |
            The Client unique identifier.
            Example: caf85feb-21f7-41cc-8277-002b5b0942dc
          required: true
          minLength: 1
          maxLength: 255
      responses:
        "204":
          description: Client was deleted.
      security:
        - OAuth2: []
    patch:
      summary: Update Client attributes
      tags:
        - Clients
      description: |
        Update the specified Client attributes,
        such as the name of a specific Client.
      operationId: patchClient
      produces:
        - application/json
      parameters:
        - name: clientId
          in: path
          type: string
          description: |
            The Client unique identifier.
            Example: caf85feb-21f7-41cc-8277-002b5b0942dc
          required: true
          minLength: 1
          maxLength: 255
        - name: request
          in: body
          schema:
            $ref: '#/definitions/ClientPatchRequest'
      responses:
        "200":
          description: Returns an updated Client.
          schema:
            $ref: '#/definitions/Client'
      security:
        - OAuth2: []
  /v1/clients/{clientId}/partitions:
    get:
      summary: Return a list of the partitions to which a Client is bound
      tags:
        - Clients
      description: |
        Returns a list of the partitions to which a specific Client is bound.
      operationId: listPartitionsOfClient
      produces:
        - application/json
      parameters:
        - name: clientId
          in: path
          type: string
          description: |
            The Client unique identifier.
            Example: caf85feb-21f7-41cc-8277-002b5b0942dc
          required: true
          minLength: 1
          maxLength: 255
      responses:
        "200":
          description: Returns a list of all the partitions to which the Client is bound.
          schema:
            type: array
            items:
              $ref: '#/definitions/Partition'
      security:
        - OAuth2: []
definitions:
  ClientCredentialsParameters:
    type: object
    required:
      - clientId
      - clientSecret
      - metadataUrl
    properties:
      clientId:
        type: string
        description: The Client id.
        example: 37cf2a58-9196-4db7-bf7f-e58e0783ed5b
      clientSecret:
        type: string
        description: The Client secret.
        example: ElIphJlj0RRusYeOg74PZFgrTbDzYKFBnkwQ8Ys8Be7208pnyTbvu0a89X02jmPN
      metadataUrl:
        type: string
        format: url
        description: The well-known OAuth2 URL associated with the Client.
  HsmServiceBindingCredentials:
    type: object
    required: [clientId, clientSecret, metadataUrl, host, port]
    properties:
      clientId:
        type: object
        minLength: 1
        example: 37cf2a58-9196-4db7-bf7f-e58e0783ed5b
      clientSecret:
        type: string
        minLength: 1
        example: ElIphJlj0RRusYeOg74PZFgrTbDzYKFBnkwQ8Ys8Be7208pnyTbvu0a89X02jmPN
      metadataUrl:
        type: string
        minLength: 1
      host:
        type: string
      port:
        type: integer
  Partition:
    type: object
    required: [name, serialNumber, deviceType, createdAt, createdBy]
    properties: &partition_properties
      name:
        type: string
        example: My Luna Cloud HSM Service Partition
        description: The partition name.
        minLength: 1
        maxLength: 100
      serialNumber:
        type: string
        example: 1269045577436
        description: The partition unique identifier.
        minLength: 1
        maxLength: 255
      deviceType:
        $ref: '#/definitions/DeviceTypeEnum'
      createdAt:
        type: string
        format: date-time
        description: The partition creation time.
        example: "2021-02-02T19:13:59Z"
      createdBy:
        type: string
        description: The partition creator.
        minLength: 1
        maxLength: 100
        example: john.dursley@gmail.com
  PartitionRequest:
    type: object
    properties:
      name:
        type: string
        example: My Luna Cloud HSM Service Partition
        description: The partition name.
        minLength: 1
        maxLength: 100
      deviceType:
        $ref: '#/definitions/DeviceTypeEnum'
        default: "cryptovisor"
  PartitionPatchRequest:
    type: object
    required: [name]
    properties:
      name:
        type: string
        example: My Luna Cloud HSM Service Partition
        description: The partition name.
        minLength: 1
        maxLength: 100
  Client:
    type: object
    required: [name, clientId, createdAt, createdBy]
    properties:
      name:
        type: string
        example: My Client
        description: The Client name.
        minLength: 1
        maxLength: 100
      clientId:
        type: string
        example: caf85feb-21f7-41cc-8277-002b5b0942dc
        description: The Client unique identifier.
        minLength: 1
        maxLength: 255
      metadataUrl:
        type: string
        format: url
        description: The well-known OAuth2 URL associated with the Client.
      createdAt:
        type: string
        format: date-time
        description: The Client creation time.
        example: 2021-02-02T19:13:59Z
      createdBy:
        type: string
        description: The Client creator.
        minLength: 1
        maxLength: 100
        example: john.dursley@gmail.com
  ClientRequest:
    type: object
    required: [partitionSerialNumber]
    properties:
      name:
        type: string
        example: My Client
        description: The Client name.
        minLength: 1
        maxLength: 100
      partitionSerialNumber:
        description: The partition unique identifier for the first partition this Client has access to.
        example: 1269045577436
        type: string
        minLength: 1
        maxLength: 255
  GrantRequest:
    type: object
    required: ["action", "serialNumber", "clientId"]
    properties:
      action:
        type: string
        enum: ["allow", "revoke"]
        example: allow
      serialNumber:
        type: string
        example: 1269045577436
        description: The partition unique identifier.
        minLength: 1
        maxLength: 255
      clientId:
        type: string
        example: caf85feb-21f7-41cc-8277-002b5b0942dc
        description: The Client unique identifier.
        minLength: 1
        maxLength: 255
  ClientPatchRequest:
    type: object
    required: [name]
    properties:
      name:
        type: string
        example: My Client
        description: The Client name.
        minLength: 1
        maxLength: 100
  DeviceTypeEnum:
    type: string
    enum: ["cryptovisor", "cryptovisor_fips"]
    default: "cryptovisor"
    example: cryptovisor
  PartitionDetails:
    type: object
    required:
      - name
      - serialNumber
      - deviceType
      - metadata
      - createdAt
      - createdBy
      - address
      - partitionCertificate
      - partitionCACertificate
      - serviceId
    allOf:
      - $ref: './cv-api.yaml#/definitions/PartitionData'
      - properties: *partition_properties
  Metadata:
    type: object
    required: [login_url]
    properties:
      login_url:
        type: string
        format: uri
      tenant_id:
        type: string
        format: uuid
  BundleCreationRequest:
    type: object
    required: ["clientId", "clientSecret"]
    properties:
      clientId:
        type: string
        description: The Client unique identifier.
        example: caf85feb-21f7-41cc-8277-002b5b0942dc
      clientSecret:
        type: string
        description: The Client secret.
        example: ElIphJlj0RRusYeOg74PZFgrTbDzYKFBnkwQ8Ys8Be7208pnyTbvu0a89X02jmPN
  SnapshotRequest:
    additionalProperties: false
    description: Request body for creating a snapshot
    properties:
      meta:
        $ref: '#/definitions/SnapshotRequestMeta'
        title: Meta
        required: true
      ttl:
        default: 7889238
        minimum: 1
        maximum: 7889238
        description: The TTL of a snapshot in seconds. The default is 3 months.
        title: Ttl
        type: integer
        example: 7889238
        required: true
    title: SnapshotRequest
    type: object
  SnapshotRequestMeta:
    additionalProperties: false
    description: Snapshot metadata in a request
    properties:
      created_by:
        default: user
        description: The user that creates the snapshot
        title: Created By
        type: string
        example: "user@email.com"
      name:
        description: The name of the snapshot
        title: Name
        type: string
        pattern: '^[a-zA-Z0-9_\-]+$'
        minLength: 1
        maxLength: 100
        required: true
        example: "user_snapshot"
      snapshot_type:
        $ref: '#/definitions/SnapshotType'
        default: user
        required: true
        description: The type of snapshot. Can only be user for requests
    title: SnapshotRequestMeta
    type: object
  SnapshotType:
    description: Enum for the type of the snapshot
    enum:
      - user
    default: user
    title: SnapshotType
    type: string
