Fortanix Plugins API

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.
  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…
      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:
    PluginSourceRequest:
      oneOf:
      - $ref: '#/components/schemas/PluginSourceRequestFromRepo'
      - $ref: '#/components/schemas/PluginSourceRequestInline'
    PluginType:
      description: Type of a plugin.
      type: string
      enum:
      - STANDARD
      - IMPERSONATING
      - CUSTOMALGORITHM
    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
    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
    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
    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
    PluginOutput:
      type: string
      format: byte
    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
    PluginVersion:
      type: string
      pattern: ^\d+.\d+$
    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
    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.
    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
    PluginSource:
      description: Plugin code that will be executed inside SGX enclave.
      oneOf:
      - $ref: '#/components/schemas/PluginSourceFromRepo'
      - $ref: '#/components/schemas/PluginSourceInline'
    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
  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