openapi: 3.2.0
info:
  title: Fortanix DSM REST Plugins API
  description: "This is a set of REST APIs for accessing the Fortanix Data Security Manager. This includes APIs for managing accounts, and for performing cryptographic and key management operations. \n\n **Note:** \n- All binary input should be base64-encoded. These fields are marked with `format: byte`. \n- For forward compatibility, any API client is expected to ignore any fields in the response not explicitly mentioned in the documentation. We reserve the right to add new fields at any time to provide new functionality without affecting existing API clients. \n- PATCH requests accept a JSON value describing a partial update to the specified resource. All top-level fields in the PATCH request are optional. If an optional field is omitted, the existing value of that field is preserved. In general, for nested JSON objects, the request must provide the complete object value rather than a partial update."
  termsOfService: https://fortanix.com/legal/agreements-and-standard-terms
  contact:
    name: Fortanix Support
    url: https://support.fortanix.com/
    email: support@fortanix.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.1.0-20260710
servers:
- url: '{dsmEndpoint}'
  description: DSM Endpoint
  variables:
    dsmEndpoint:
      default: https://amer.smartkey.io
      description: Type your DSM server URL here (include https://)
tags:
- name: Plugins
paths:
  /sys/v1/plugins:
    post:
      operationId: CreatePlugin
      tags:
      - Plugins
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Create a new plugin.
      description: Create a new plugin.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginRequest'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
    get:
      operationId: ListPlugins
      tags:
      - Plugins
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Get details of all plugins accessible to the requester.
      description: Get details of all plugins accessible to the requester.
      parameters:
      - $ref: '#/components/parameters/ListPluginsParams'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plugin'
  /sys/v1/plugins/{plugin_id}:
    delete:
      operationId: DeletePlugin
      tags:
      - Plugins
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Delete a plugin.
      description: Delete a plugin.
      parameters:
      - name: plugin_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Nothing is returned on success
    get:
      operationId: GetPlugin
      tags:
      - Plugins
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Lookup a plugin.
      description: Lookup a plugin.
      parameters:
      - name: plugin_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
    post:
      operationId: InvokePlugin
      tags:
      - Plugins
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: 'Invokes a plugin execution with the provided request body

        as input to the plugin.'
      description: 'Invokes a plugin execution with the provided request body

        as input to the plugin.'
      parameters:
      - name: plugin_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema: {}
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginOutput'
    patch:
      operationId: UpdatePlugin
      tags:
      - Plugins
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: 'Change a plugin''s properties, such as name, description,

        code, group membership, etc.'
      description: 'Change a plugin''s properties, such as name, description,

        code, group membership, etc.'
      parameters:
      - name: plugin_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginRequest'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
components:
  schemas:
    PluginSourceInline:
      allOf:
      - type: object
        properties:
          language:
            $ref: '#/components/schemas/Language'
          code:
            type: string
        required:
        - language
        - code
    PluginSourceRequestFromRepo:
      allOf:
      - type: object
        properties:
          repo_url:
            type: string
          plugin_name:
            type: string
          version:
            $ref: '#/components/schemas/PluginVersion'
        required:
        - repo_url
        - plugin_name
        - version
    ListPluginsParams:
      allOf:
      - type: object
        description: Query parameters to get Plugins.
        properties:
          group_id:
            type: string
            format: uuid
            description: Group for which the associated plugins should be retrieved.
          limit:
            type: integer
            description: Maximum number of entries to return.
          offset:
            type: integer
            description: Starting offset.
      - $ref: '#/components/schemas/PluginSort'
    OauthScope:
      description: OAuth scope.
      type: string
      enum:
      - app
      - openid
      - email
      - profile
    PluginRequest:
      allOf:
      - type: object
        properties:
          default_group:
            type:
            - string
            - 'null'
            format: uuid
            description: The default group a plugin belongs to.
          description:
            type:
            - string
            - 'null'
            description: Description of the plugin.
          enabled:
            type:
            - boolean
            - 'null'
            description: Is plugin enabled.
          name:
            type:
            - string
            - 'null'
            maxLength: 4096
            pattern: ^[^\n]*[^\s\n][^\n]*$
            description: Name of the plugin, which must be unique within an account.
          plugin_type:
            $ref: '#/components/schemas/PluginType'
          signature:
            type:
            - string
            - 'null'
            description: 'A detached OpenPGP signature over the plugin source code.


              The signature packet must be armored. If the account has a plugin code signing

              policy, the signature is required in the following cases:

              - when creating a new plugin

              - when updating the plugin code'
          source:
            $ref: '#/components/schemas/PluginSourceRequest'
          add_groups:
            type:
            - array
            - 'null'
            uniqueItems: true
            items:
              type: string
              format: uuid
            description: Set of all the groups that plugin is part of.
          del_groups:
            type:
            - array
            - 'null'
            uniqueItems: true
            items:
              type: string
              format: uuid
            description: Set of all the groups that plugin is part of.
          mod_groups:
            type:
            - array
            - 'null'
            uniqueItems: true
            items:
              type: string
              format: uuid
            description: Set of all the groups that plugin is part of.
    PluginOutput:
      type: string
      format: byte
    Principal:
      description: A security principal.
      oneOf:
      - title: PrincipalVariantApp
        type: object
        properties:
          app:
            type: string
            format: uuid
        required:
        - app
      - title: PrincipalVariantUser
        type: object
        properties:
          user:
            type: string
            format: uuid
        required:
        - user
      - title: PrincipalVariantPlugin
        type: object
        properties:
          plugin:
            type: string
            format: uuid
        required:
        - plugin
      - title: PrincipalVariantUserViaApp
        type: object
        properties:
          userviaapp:
            $ref: '#/components/schemas/PrincipalUserViaApp'
        required:
        - userviaapp
      - title: PrincipalVariantSystem
        type: string
        enum:
        - system
      - title: PrincipalVariantUnregisteredUser
        type: string
        enum:
        - unregistereduser
    PrincipalUserViaApp:
      allOf:
      - type: object
        description: UserViaApp signifies a user authorizing some app to act on its behalf through OAuth.
        properties:
          user_id:
            type: string
            format: uuid
          scopes:
            type: array
            uniqueItems: true
            items:
              $ref: '#/components/schemas/OauthScope'
        required:
        - user_id
        - scopes
    Plugin:
      allOf:
      - type: object
        properties:
          acct_id:
            type: string
            format: uuid
            description: The id of the Account that the plugin belongs to.
          created_at:
            type: string
            pattern: ^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$
            example: 20170509T070912Z
            description: Timestamp when the plugin was created.
          creator:
            $ref: '#/components/schemas/Principal'
          default_group:
            type: string
            format: uuid
            description: The default group a plugin belongs to.
          description:
            type:
            - string
            - 'null'
            description: Description of the plugin.
          enabled:
            type: boolean
            description: Is plugin enabled.
          lastrun_at:
            type: string
            pattern: ^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$
            example: 20170509T070912Z
            description: Timestamp when the plugin was most recently used.
          lastupdated_at:
            type: string
            pattern: ^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$
            example: 20170509T070912Z
            description: Timestamp when the plugin was most recently updated.
          legacy_access:
            type: boolean
            description: 'If a requester is updating/using a Plugin they must have the relevant

              permissions in all Groups that Plugin has access to. But for legacy Plugins,

              the requester is required to have relevant permissions in any one of the groups

              that Plugin has access to.'
          name:
            type: string
            maxLength: 4096
            pattern: ^[^\n]*[^\s\n][^\n]*$
            description: Name of the plugin, which must be unique within an account.
          plugin_id:
            type: string
            format: uuid
            description: Unique id to identify a plugin.
          plugin_type:
            $ref: '#/components/schemas/PluginType'
          source:
            $ref: '#/components/schemas/PluginSource'
          groups:
            type: array
            uniqueItems: true
            items:
              type: string
              format: uuid
            description: Set of all the groups that plugin is part of.
        required:
        - acct_id
        - created_at
        - creator
        - default_group
        - enabled
        - lastupdated_at
        - legacy_access
        - name
        - plugin_id
        - plugin_type
        - source
        - groups
    PluginVersion:
      type: string
      pattern: ^\d+.\d+$
    PluginSource:
      description: Plugin code that will be executed inside SGX enclave.
      oneOf:
      - $ref: '#/components/schemas/PluginSourceFromRepo'
      - $ref: '#/components/schemas/PluginSourceInline'
    PluginSort:
      oneOf:
      - title: PluginSortVariantByPluginId
        type: object
        description: Sort plugins by Plugin Id.
        properties:
          sort:
            type: string
            pattern: ^plugin_id:(?:asc|desc)$
            example: plugin_id:asc
          start:
            type: string
            format: uuid
            description: Starting offset(UUID of plugin).
        required:
        - sort
    PluginSourceRequest:
      oneOf:
      - $ref: '#/components/schemas/PluginSourceRequestFromRepo'
      - $ref: '#/components/schemas/PluginSourceRequestInline'
    PluginSourceRequestInline:
      allOf:
      - type: object
        properties:
          language:
            $ref: '#/components/schemas/Language'
          code:
            type: string
        required:
        - language
        - code
    Language:
      description: Language of plugin code.
      type: string
      enum:
      - LUA
    PluginSourceFromRepo:
      allOf:
      - type: object
        properties:
          repo_url:
            type: string
          name:
            type: string
          version:
            $ref: '#/components/schemas/PluginVersion'
          language:
            $ref: '#/components/schemas/Language'
          code:
            type: string
        required:
        - repo_url
        - name
        - version
        - language
        - code
    PluginType:
      description: Type of a plugin.
      type: string
      enum:
      - STANDARD
      - IMPERSONATING
      - CUSTOMALGORITHM
  parameters:
    ListPluginsParams:
      in: query
      name: ListPluginsParams
      schema:
        $ref: '#/components/schemas/ListPluginsParams'
      explode: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    apiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
      description: Please enter your token prefixed with 'Basic ' (e.g., 'Basic your_token_here')
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT