openapi: 3.2.0
info:
  title: Fortanix DSM REST Misc 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: Misc
paths:
  /sys/v1/services:
    get:
      operationId: GetAllServices
      tags:
      - Misc
      summary: Check information about all connected services
      description: Returns the information regarding the status of all the connected services.
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllServicesResponse'
  /sys/v1/health:
    get:
      operationId: GetHealth
      tags:
      - Misc
      summary: Check whether the server is handling requests
      description: 'Returns a 200-class status code if the server is handling requests,

        or a 500-class status code if the server is having problems.'
      parameters:
      - $ref: '#/components/parameters/HealthParams'
      responses:
        '204':
          description: Nothing is returned on success
  /sys/v1/services/{name}:
    get:
      operationId: GetService
      tags:
      - Misc
      summary: Check information about the specified service
      description: Returns the information regarding the status of the specified service.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          maxLength: 4096
          pattern: ^[^\n]*[^\s\n][^\n]*$
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
  /sys/v1/ldap/search/{ldap_id}:
    post:
      operationId: LdapSearch
      tags:
      - Misc
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Searches for LDAP objects in the specified LDAP directory.
      description: Searches for LDAP objects in the specified LDAP directory.
      parameters:
      - name: ldap_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LdapSearchRequest'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LdapSearchResultEntry'
  /saml/metadata.xml:
    get:
      operationId: SamlSpMetadata
      tags:
      - Misc
      summary: Get the SP metadata file for SAML configuration
      description: 'Returns the Service Provider metadata file of this cluster, for SAML

        configuration. If this cluster has a SAML signing key, the public key is

        included in the SPSSODescriptor.'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                  minimum: 0
                  maximum: 255
  /sys/v1/info:
    get:
      operationId: SystemInfo
      tags:
      - Misc
      summary: Returns info about the system.
      description: Returns info about the system.
      parameters:
      - $ref: '#/components/parameters/SystemInfoParams'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInfoResponse'
  /sys/v1/ldap/test:
    post:
      operationId: TestLdapConfig
      tags:
      - Misc
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Test connection using the ldap SSO configuration saved in the account.
      description: Test connection using the ldap SSO configuration saved in the account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LdapTestRequest'
      responses:
        '204':
          description: Nothing is returned on success
  /sys/v1/tls_certificates:
    get:
      operationId: TlsCertsSpki
      tags:
      - Misc
      summary: 'Returns all TLS Certs SPKIs of the DSM endpoints

        Deprecated(legacy), please use API "/sys/v1/tls_public_keys" instead'
      description: 'Returns all TLS Certs SPKIs of the DSM endpoints

        Deprecated(legacy), please use API "/sys/v1/tls_public_keys" instead'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TlsCertsSpkiResponse'
  /sys/v1/tls_public_keys:
    get:
      operationId: TlsPublicKeys
      tags:
      - Misc
      summary: Returns all TLS Certs SPKIs of the DSM endpoints
      description: Returns all TLS Certs SPKIs of the DSM endpoints
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TlsPublicKeysResponse'
components:
  schemas:
    LdapAuthorizationConfig:
      allOf:
      - type: object
        description: LDAP authorization settings.
        properties:
          valid_for:
            type: integer
            description: Number of seconds after which the authorization should be checked again.
          require_role:
            type:
            - object
            - 'null'
            additionalProperties:
              type: string
            description: 'A map from account roles to distinguished names of LDAP groups.

              If a DN is specified for an account role, entities with that role

              must be a member of the specified LDAP group.'
          user_self_provisioning:
            $ref: '#/components/schemas/LdapUserSelfProvisioningConfig'
          role_conflict_resolution:
            $ref: '#/components/schemas/LdapRoleConflictResolution'
        required:
        - valid_for
    SystemInfoResponse:
      allOf:
      - type: object
        description: Information about the service version.
        properties:
          external_entropy:
            $ref: '#/components/schemas/ExternalEntropyInfo'
      - $ref: '#/components/schemas/VersionResponse'
    CaConfig:
      description: CA settings.
      oneOf:
      - title: CaConfigVariantCaSet
        type: object
        properties:
          ca_set:
            $ref: '#/components/schemas/CaSet'
        required:
        - ca_set
      - title: CaConfigVariantPinned
        type: object
        properties:
          pinned:
            type: array
            items:
              type: string
              format: byte
        required:
        - pinned
    LegacyLdapAccountRole:
      description: Role of a user or app in an account for the purpose of LDAP configurations.
      type: string
      enum:
      - ADMIN_USER
      - MEMBER_USER
      - AUDITOR_USER
      - ADMIN_APP
      - CRYPTO_APP
    Service:
      allOf:
      - type: object
        properties:
          name:
            type: string
          hostnames:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/HostnameInfo'
        required:
        - name
        - hostnames
    ServerMode:
      description: Server execution mode.
      type: string
      enum:
      - Software
      - Sgx
    SystemInfoParams:
      allOf:
      - type: object
        properties:
          detailed_fips_info:
            type: boolean
            description: 'Include FIPS-relevant info in the response. Currently that is `plugins_digest`.


              Only applicable to FIPS builds.'
    TlsCertificateSpki:
      allOf:
      - type: object
        properties:
          cert_spki:
            type: string
            format: byte
            description: The TbsCertificate's spki value.
          is_active:
            type: boolean
            description: True if the certificate is currently active.
        required:
        - cert_spki
        - is_active
    TlsPublicKeysResponse:
      allOf:
      - type: object
        properties:
          tls_public_keys:
            type: array
            items:
              $ref: '#/components/schemas/TlsPublicKeyInfo'
            description: 'A list of SPKIs(public keys) from leaf server certificates used for

              TLS connections by DSM.'
        required:
        - tls_public_keys
    LdapSearchScope:
      type: string
      enum:
      - single-level
      - whole-subtree
    LdapSearchResultEntry:
      allOf:
      - type: object
        properties:
          distinguished_name:
            type: string
          ldap_object_id:
            type: string
            format: uuid
          common_name:
            type: array
            items:
              type: string
          description:
            type: array
            items:
              type: string
          object_class:
            type: array
            items:
              type: string
          mail:
            type:
            - string
            - 'null'
          user_principal_name:
            type:
            - string
            - 'null'
        required:
        - distinguished_name
        - ldap_object_id
        - common_name
        - description
        - object_class
    TlsConfigRequired:
      allOf:
      - type: object
        properties:
          validate_hostname:
            type: boolean
          ca:
            $ref: '#/components/schemas/CaConfig'
          client_key:
            type: string
            format: byte
          client_cert:
            type: string
            format: byte
        required:
        - validate_hostname
        - ca
    TlsConfigVariantOpportunistic:
      allOf:
      - type: object
        properties:
          mode:
            type: string
            enum:
            - opportunistic
        required:
        - mode
      - type: object
        properties: {}
    LdapDnResolutionConstruct:
      allOf:
      - type: object
        description: Transform the user email through a pattern to derive the DN.
        properties:
          domain_format:
            type: object
            additionalProperties:
              type: string
            description: 'For example: "example.com" => "uid={},ou=users,dc=example,dc=com".'
        required:
        - domain_format
    UserAccountFlags:
      description: User's role(s) and state in an account.
      allOf:
      - type: array
        uniqueItems: true
        items:
          $ref: '#/components/schemas/UserAccountFlagOrRole'
    LdapTestRequest:
      allOf:
      - type: object
        properties:
          ldap:
            $ref: '#/components/schemas/AuthConfigLdap'
          test_credentials:
            $ref: '#/components/schemas/LdapTestCredentials'
        required:
        - ldap
    VersionResponse:
      allOf:
      - type: object
        description: Information about the service version.
        properties:
          version:
            type: string
            description: Server version. This is encoded as "major.minor.build".
          api_version:
            type: string
            description: The API version implemented by the server.
          server_mode:
            $ref: '#/components/schemas/ServerMode'
          fips_level:
            type:
            - integer
            - 'null'
            minimum: 0
            maximum: 255
            description: 'FIPS level at which the service in running. If this field is absent, then the service is

              not running in FIPS compliant mode.'
          plugins_digest:
            type: string
            format: byte
            description: 'An opaque digest of all current plugins.


              Only present when the server is running in FIPS mode.'
        required:
        - version
        - api_version
        - server_mode
    LdapDnResolutionVariantSearchByMail:
      allOf:
      - type: object
        properties:
          method:
            type: string
            enum:
            - search-by-mail
        required:
        - method
      - type: object
        properties: {}
    TlsPublicKeyInfo:
      allOf:
      - type: object
        properties:
          spki:
            type: string
            format: byte
            description: The TbsCertificate's spki value.
          is_active:
            type: boolean
            description: True if the certificate is currently active.
        required:
        - spki
        - is_active
    ExternalEntropySourceInfo:
      allOf:
      - type: object
        properties:
          name:
            type: string
          description:
            type:
            - string
            - 'null'
        required:
        - name
    HostnameInfo:
      allOf:
      - type: object
        properties:
          health_status:
            $ref: '#/components/schemas/HealthStatus'
          last_health_check:
            $ref: '#/components/schemas/HealthCheckInfo'
        required:
        - health_status
    LdapSearchFilter:
      allOf:
      - type: object
        properties:
          name:
            type: string
          value:
            type: string
        required:
        - name
        - value
    HealthStatus:
      type: string
      enum:
      - Healthy
      - Unhealthy
    LdapPrincipal:
      oneOf:
      - $ref: '#/components/schemas/LdapPrincipalUnresolved'
      - $ref: '#/components/schemas/LdapPrincipalResolved'
    AuthConfigLdap:
      allOf:
      - type: object
        description: LDAP authentication settings.
        properties:
          name:
            type: string
            description: A user-visible name to give this LDAP integration.
          icon_url:
            type: string
            description: 'The URL hosting an image to display for this LDAP integration.

              An empty string can also be specified (to indicate that no

              icon needs to be displayed).'
          ldap_url:
            type: string
            description: The URL of the LDAP server, e.g., "ldap://example.org".
          dn_resolution:
            $ref: '#/components/schemas/LdapDnResolution'
          tls:
            $ref: '#/components/schemas/TlsConfig'
          base_dn:
            type:
            - string
            - 'null'
            description: 'The subtree from which to perform LDAP searches; for example,

              "OU=users,DC=example,DC=org".'
          user_object_class:
            type:
            - string
            - 'null'
            description: 'The LDAP object class (e.g., "User") to use when looking up

              DSM users trying to authenticate. This field is required if

              the DN resolution method is search-by-mail or if authorization

              settings are enabled for this LDAP integraton.'
          service_account:
            $ref: '#/components/schemas/LdapServiceAccount'
          authorization:
            $ref: '#/components/schemas/LdapAuthorizationConfig'
        required:
        - name
        - icon_url
        - ldap_url
        - dn_resolution
        - tls
    LdapServiceAccount:
      allOf:
      - type: object
        description: Credentials used by the service to authenticate itself to an LDAP server.
        properties:
          dn:
            type: string
            description: Distinguished name of the service account.
          password:
            type: string
            description: The password for the service account.
        required:
        - dn
        - password
    LdapRoleConflictResolution:
      description: 'Controls how we resolve conflicting role assignments with LDAP authorization.


        When users are authorized through LDAP, their DSM group memberships are

        determined by their LDAP groups and the external role mappings created in

        DSM. For example, if the user belongs to 3 LDAP groups A, B and C, and these

        LDAP groups are mapped to DSM groups G1 and G2 in the following way:

        - A -> G1 as "group auditor"

        - B -> G1 as "group administrator"

        - C -> G2 as "group administrator"

        Then which role should be assigned to this user in G1?


        The answer to this question used to be simple before the introduction of

        custom user roles in DSM: we took the maximum of the roles. Note that the

        legacy roles (group admin/auditor) formed a strict "more powerful than"

        relation, i.e. group administrator is strictly more powerful than group

        auditor (and same is true for legacy account roles). However, custom user

        roles do not have that relationship anymore. Moreover, the legacy behavior

        is not quite square with the role exclusivity rules either since the legacy

        behavior can also be regarded as assigning multiple exclusive roles in the

        same group.


        After the introduction of custom user roles, we allow a user to have

        multiple roles in one group as long as none of the roles are marked as

        exclusive. That rule is easily enforceable in the user Invite API. With LDAP

        authorization, the group memberships are computed dynamically when the

        Select Account API is called and it is possible that we run into conflicting

        role assignments due to user''s LDAP group membership and current mappings

        between external roles (i.e. LDAP groups) and DSM groups.'
      type: string
      enum:
      - backcompat_legacy_roles_only
      - disregard_exclusive_roles
    ExternalEntropyInfo:
      allOf:
      - type: object
        description: Information about the service version.
        properties:
          external_entropy_sources:
            type: array
            items:
              $ref: '#/components/schemas/ExternalEntropySourceInfo'
        required:
        - external_entropy_sources
    UserAccountFlagOrRole:
      description: User account flag or legacy user account role name or custom role id
      oneOf:
      - $ref: '#/components/schemas/UserAccountFlag'
      - $ref: '#/components/schemas/LegacyUserAccountRole'
      - type: string
        format: uuid
    LdapDnResolution:
      description: 'Distinguished Name (DN) resolution method. Given a user''s email address, a DN resolution method

        is used to find the user''s DN in an LDAP directory.'
      oneOf:
      - $ref: '#/components/schemas/LdapDnResolutionVariantConstruct'
      - $ref: '#/components/schemas/LdapDnResolutionVariantSearchByMail'
      - $ref: '#/components/schemas/LdapDnResolutionVariantUserPrincipalName'
      discriminator:
        propertyName: method
        mapping:
          construct: LdapDnResolutionVariantConstruct
          search-by-mail: LdapDnResolutionVariantSearchByMail
          upn: LdapDnResolutionVariantUserPrincipalName
    LdapSearchRequest:
      allOf:
      - type: object
        properties:
          base_dn:
            type:
            - string
            - 'null'
          filters:
            type: array
            items:
              $ref: '#/components/schemas/LdapSearchFilter'
          object_class:
            type:
            - string
            - 'null'
          scope:
            $ref: '#/components/schemas/LdapSearchScope'
        required:
        - filters
        - scope
    LdapPrincipalUnresolved:
      allOf:
      - type: object
        properties:
          email:
            type: string
            format: email
        required:
        - email
    HealthCheckInfo:
      allOf:
      - type: object
        properties:
          initiated_at:
            type: string
            pattern: ^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$
            example: 20170509T070912Z
            description: The time the health check was initiated.
          finished_at:
            type: string
            pattern: ^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$
            example: 20170509T070912Z
            description: The time the health check finished (regardless of its outcome).
          result:
            type: string
            description: The result of the health check.
        required:
        - initiated_at
        - finished_at
        - result
    LdapUserSelfProvisioningConfig:
      allOf:
      - type: object
        description: 'LDAP user self-provisioning settings. Currently, the only

          setting available for configuration is the mapping from

          LDAP users to DSM account roles.'
        properties:
          role_assignment:
            $ref: '#/components/schemas/LdapUserSelfProvisioningRole'
        required:
        - role_assignment
    GetAllServicesResponse:
      allOf:
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/Service'
        required:
        - items
    TlsConfigVariantRequired:
      allOf:
      - type: object
        properties:
          mode:
            type: string
            enum:
            - required
        required:
        - mode
      - $ref: '#/components/schemas/TlsConfigRequired'
    LdapDnResolutionVariantUserPrincipalName:
      allOf:
      - type: object
        properties:
          method:
            type: string
            enum:
            - upn
        required:
        - method
      - type: object
        properties: {}
    CaSet:
      description: Predefined CA sets.
      type: string
      enum:
      - global_roots
    LdapUserSelfProvisioningRoleVariantFixed:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - Fixed
        required:
        - $type
      - $ref: '#/components/schemas/LdapUserSelfProvisioningRoleFixed'
    TlsConfig:
      description: TLS client settings.
      oneOf:
      - $ref: '#/components/schemas/TlsConfigVariantDisabled'
      - $ref: '#/components/schemas/TlsConfigVariantOpportunistic'
      - $ref: '#/components/schemas/TlsConfigVariantRequired'
      discriminator:
        propertyName: mode
        mapping:
          disabled: TlsConfigVariantDisabled
          opportunistic: TlsConfigVariantOpportunistic
          required: TlsConfigVariantRequired
    LdapUserSelfProvisioningRoleFixed:
      allOf:
      - type: object
        description: 'Map all self-provisioned users to a single specified account role.

          (Note that this setting only determines the role that a self-

          provisioned user starts with; an account admin can change any user''s

          role at a later time.) A "state enabled" flag will be implicitly added,

          and any specified "pending invite" flag will be removed.'
        properties:
          role:
            $ref: '#/components/schemas/UserAccountFlags'
        required:
        - role
    TlsConfigVariantDisabled:
      allOf:
      - type: object
        properties:
          mode:
            type: string
            enum:
            - disabled
        required:
        - mode
      - type: object
        properties: {}
    LdapPrincipalResolved:
      allOf:
      - type: object
        properties:
          dn:
            type: string
        required:
        - dn
    LdapAccountRole:
      description: Role of a user or app in an account for the purpose of LDAP configurations.
      oneOf:
      - $ref: '#/components/schemas/LegacyLdapAccountRole'
      - type: string
        format: uuid
    TlsCertsSpkiResponse:
      allOf:
      - type: object
        properties:
          tls_certificates_info:
            type: array
            items:
              $ref: '#/components/schemas/TlsCertificateSpki'
            description: 'A list of leaf server certificates used for

              TLS connections by DSM.'
        required:
        - tls_certificates_info
    HealthParams:
      allOf:
      - type: object
        properties:
          consistency:
            type: string
          check_queues:
            type: boolean
    LdapTestCredentials:
      allOf:
      - type: object
        properties:
          password:
            type: string
          account_role:
            $ref: '#/components/schemas/LdapAccountRole'
        required:
        - password
      - $ref: '#/components/schemas/LdapPrincipal'
    LegacyUserAccountRole:
      description: Legacy user account role
      type: string
      enum:
      - ACCOUNTADMINISTRATOR
      - ACCOUNTMEMBER
      - ACCOUNTAUDITOR
    LdapDnResolutionVariantConstruct:
      allOf:
      - type: object
        properties:
          method:
            type: string
            enum:
            - construct
        required:
        - method
      - $ref: '#/components/schemas/LdapDnResolutionConstruct'
    UserAccountFlag:
      description: User account flag
      type: string
      enum:
      - STATEENABLED
      - PENDINGINVITE
    LdapUserSelfProvisioningRole:
      description: 'A structure indicating how self-provisioned LDAP users will

        be assigned account roles.'
      oneOf:
      - $ref: '#/components/schemas/LdapUserSelfProvisioningRoleVariantFixed'
      discriminator:
        propertyName: $type
        mapping:
          Fixed: LdapUserSelfProvisioningRoleVariantFixed
  parameters:
    SystemInfoParams:
      in: query
      name: SystemInfoParams
      schema:
        $ref: '#/components/schemas/SystemInfoParams'
      explode: true
    HealthParams:
      in: query
      name: HealthParams
      schema:
        $ref: '#/components/schemas/HealthParams'
      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