openapi: 3.2.0
info:
  title: Fortanix DSM REST Credentials 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: Credentials
paths:
  /sys/v1/credentials:
    post:
      operationId: CreateCredential
      tags:
      - Credentials
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Create a new integration credential
      description: Create a new integration credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCredentialCreateRequest'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationCredential'
    get:
      operationId: GetAllCredentials
      tags:
      - Credentials
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Get all credentials accessible to the requester
      description: Get all credentials accessible to the requester
      parameters:
      - $ref: '#/components/parameters/ListCredentialsParams'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCredentialsResponse'
  /sys/v1/credentials/{cred_id}:
    delete:
      operationId: DeleteCredential
      tags:
      - Credentials
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Delete a credential by id
      description: Delete a credential by id
      parameters:
      - name: cred_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Nothing is returned on success
    get:
      operationId: GetCredential
      tags:
      - Credentials
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Get a credential specified by id
      description: Get a credential specified by id
      parameters:
      - name: cred_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationCredential'
    patch:
      operationId: UpdateCredential
      tags:
      - Credentials
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Update a credential object
      description: Update a credential object
      parameters:
      - name: cred_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCredentialUpdateRequest'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationCredential'
  /sys/v1/credentials/{cred_id}/rotate:
    post:
      operationId: RotateCredential
      tags:
      - Credentials
      security:
      - bearerToken: []
      - apiKeyAuth: []
      summary: Rotate a specified credential
      description: Rotate a specified credential
      parameters:
      - name: cred_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCredentialRotationRequest'
      responses:
        2XX:
          description: Success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationCredential'
components:
  schemas:
    OciCredentialAuth:
      oneOf:
      - $ref: '#/components/schemas/OciCredentialAuthVariantApiKey'
      discriminator:
        propertyName: $type
        mapping:
          ApiKey: OciCredentialAuthVariantApiKey
    AzureCredentialAuthCertificate:
      allOf:
      - type: object
        description: 'OAuth2 client credentials with a certificate.

          Azure AD verifies the JWT using the uploaded certificate''s public key'
        properties:
          tenant_id:
            type: string
            description: Directory (tenant) ID of the Azure application
          client_id:
            type: string
            description: Application (client) ID of the Azure application
          client_cert:
            $ref: '#/components/schemas/SobjectId'
          client_key:
            $ref: '#/components/schemas/SobjectId'
        required:
        - tenant_id
        - client_id
        - client_cert
        - client_key
    SobjectId:
      description: 'A wrapper type to provide better clarity that the id referenced

        is a security object.'
      allOf:
      - type: string
        format: uuid
    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
    RotationMethod:
      description: 'Describes the how to rotate the credential and any additional information

        that is required for that to happen successfully.'
      oneOf:
      - $ref: '#/components/schemas/RotationMethodVariantGenerate'
      discriminator:
        propertyName: $type
        mapping:
          Generate: RotationMethodVariantGenerate
    OauthScope:
      description: OAuth scope.
      type: string
      enum:
      - app
      - openid
      - email
      - profile
    IntegrationCredential:
      allOf:
      - type: object
        properties:
          created_at:
            type: string
            pattern: ^\d{4}\d{2}\d{2}T\d{2}\d{2}\d{2}Z$
            example: 20170509T070912Z
            description: The time the credential was created
          creator:
            $ref: '#/components/schemas/Principal'
          credential_details:
            $ref: '#/components/schemas/CredentialDetails'
          credential_id:
            type: string
            format: uuid
          description:
            type:
            - string
            - 'null'
          group_id:
            type: string
            format: uuid
            description: The ID of the group that this credential is associated with
          name:
            type: string
            maxLength: 4096
            pattern: ^[^\n]*[^\s\n][^\n]*$
            description: The human readable name of the credential
        required:
        - created_at
        - creator
        - credential_details
        - credential_id
        - group_id
        - name
    OciCredentialAuthApiKey:
      allOf:
      - type: object
        description: '**NOTE**: This is not to be confused with a static long-lived token.'
        properties:
          user_ocid:
            type: string
            description: 'The user''s OCID from Oracle who will have the public key

              configured as an "API Key" on Oracle servers. That public

              key is part of the key-pair represented by `signing_key`.'
          tenant_ocid:
            type: string
            description: The tenant OCID from Oracle
          signing_key:
            $ref: '#/components/schemas/SobjectId'
        required:
        - user_ocid
        - tenant_ocid
        - signing_key
    CredentialDetailsVariantOci:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - Oci
          body:
            $ref: '#/components/schemas/OciCredentialAuth'
        required:
        - $type
        - body
    ListCredentialsMetadata:
      allOf:
      - type: object
        properties:
          total_count:
            type: integer
          filtered_count:
            type: integer
        required:
        - total_count
        - filtered_count
    AzureCredentialAuthVariantClientSecret:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - ClientSecret
        required:
        - $type
      - $ref: '#/components/schemas/AzureCredentialAuthClientSecret'
    ListCredentialsResponse:
      allOf:
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/IntegrationCredential'
          metadata:
            $ref: '#/components/schemas/ListCredentialsMetadata'
        required:
        - items
        - metadata
    ListCredentialsParams:
      allOf:
      - type: object
        properties:
          limit:
            type: integer
            description: 'Set the max number of credentials to be returned in the response (default: 1000).'
          offset:
            type: integer
            description: Skip first n (offset) matches
          filter:
            type: string
            description: Allows for more specific filters on the credential.
      - $ref: '#/components/schemas/CredentialSort'
    OciCredentialAuthVariantApiKey:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - ApiKey
        required:
        - $type
      - $ref: '#/components/schemas/OciCredentialAuthApiKey'
    RotationMethodVariantGenerate:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - Generate
        required:
        - $type
      - type: object
        properties: {}
    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
    AzureCredentialAuth:
      description: Authentication configuration for Azure integrations that use Credential Objects.
      oneOf:
      - $ref: '#/components/schemas/AzureCredentialAuthVariantClientSecret'
      - $ref: '#/components/schemas/AzureCredentialAuthVariantCertificate'
      discriminator:
        propertyName: $type
        mapping:
          ClientSecret: AzureCredentialAuthVariantClientSecret
          Certificate: AzureCredentialAuthVariantCertificate
    IntegrationCredentialUpdateRequest:
      allOf:
      - type: object
        properties:
          credential_details:
            $ref: '#/components/schemas/CredentialDetails'
          description:
            type:
            - string
            - 'null'
          name:
            type:
            - string
            - 'null'
            maxLength: 4096
            pattern: ^[^\n]*[^\s\n][^\n]*$
            description: The human readable name of the credential
    IntegrationCredentialRotationRequest:
      allOf:
      - type: object
        properties:
          method:
            $ref: '#/components/schemas/RotationMethod'
        required:
        - method
    CredentialSort:
      oneOf:
      - title: CredentialSortVariantByCredentialId
        type: object
        description: Sort the credentials on the basis of the credential_id
        properties:
          sort_by:
            type: string
            pattern: ^credential_id:(?:asc|desc)$
            example: credential_id:asc
        required:
        - sort_by
      - title: CredentialSortVariantByCredentialName
        type: object
        description: Sort credentials on the basis of the credential name
        properties:
          sort_by:
            type: string
            pattern: ^credential_name:(?:asc|desc)$
            example: credential_name:asc
        required:
        - sort_by
    CredentialDetails:
      description: 'Describes the authentication type for a given integration.


        This type is the "backbone" to the credential objects in DSM as it''s what

        contains the relevant information and references to the sobject(s) needed to authenticate

        to external systems/services.'
      oneOf:
      - $ref: '#/components/schemas/CredentialDetailsVariantOci'
      - $ref: '#/components/schemas/CredentialDetailsVariantAzure'
      discriminator:
        propertyName: $type
        mapping:
          Oci: CredentialDetailsVariantOci
          Azure: CredentialDetailsVariantAzure
    AzureCredentialAuthVariantCertificate:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - Certificate
        required:
        - $type
      - $ref: '#/components/schemas/AzureCredentialAuthCertificate'
    CredentialDetailsVariantAzure:
      allOf:
      - type: object
        properties:
          $type:
            type: string
            enum:
            - Azure
          body:
            $ref: '#/components/schemas/AzureCredentialAuth'
        required:
        - $type
        - body
    AzureCredentialAuthClientSecret:
      allOf:
      - type: object
        description: 'OAuth2 client credentials with a client secret value.

          The `tenant_id` and `client_id` is here as well as we

          need these to get a token from the client credentials flow.'
        properties:
          tenant_id:
            type: string
            description: Directory (tenant) ID of the Azure application
          client_id:
            type: string
            description: Application (client) ID of the Azure application
          client_secret:
            $ref: '#/components/schemas/SobjectId'
        required:
        - tenant_id
        - client_id
        - client_secret
    IntegrationCredentialCreateRequest:
      allOf:
      - type: object
        properties:
          credential_details:
            $ref: '#/components/schemas/CredentialDetails'
          description:
            type:
            - string
            - 'null'
          group_id:
            type: string
            format: uuid
            description: The ID of the group that this credential is associated with
          name:
            type: string
            maxLength: 4096
            pattern: ^[^\n]*[^\s\n][^\n]*$
            description: The human readable name of the credential
        required:
        - credential_details
        - group_id
        - name
  parameters:
    ListCredentialsParams:
      in: query
      name: ListCredentialsParams
      schema:
        $ref: '#/components/schemas/ListCredentialsParams'
      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