> ## Documentation Index
> Fetch the complete documentation index at: https://support.fortanix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a session for a user or an app.

> Authenticate a user or an app to begin a session.
The caller needs to provide a basic authentication token or
an appropriate request body (see input type).
The response body contains a bearer authentication token
which needs to be provided by subsequent calls for the
duration of the session.

If this is basic auth and the user has MFA devices configured,
the response also contains challenge for the device to sign.
Until the signed assertion is passed to `POST /sys/v1/session/auth/2fa/fido2`
to complete 2FA, the bearer token can't be used for anything else.

## OpenAPI

````json POST /sys/v1/session/auth
{
  "openapi": "3.0.0",
  "info": {
    "title": "Fortanix DSM REST 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.",
    "termsOfService": "https://www.fortanix.com/legal/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-20260526"
  },
  "servers": [
    {
      "url": "https://amer.smartkey.io"
    }
  ],
  "paths": {
    "/sys/v1/session/auth": {
      "post": {
        "operationId": "Authenticate",
        "tags": [
          "Session"
        ],
        "security": [
          {
            "basicAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "summary": "Create a session for a user or an app.",
        "description": "Authenticate a user or an app to begin a session.\nThe caller needs to provide a basic authentication token or\nan appropriate request body (see input type).\nThe response body contains a bearer authentication token\nwhich needs to be provided by subsequent calls for the\nduration of the session.\n\nIf this is basic auth and the user has MFA devices configured,\nthe response also contains challenge for the device to sign.\nUntil the signed assertion is passed to `POST /sys/v1/session/auth/2fa/fido2`\nto complete 2FA, the bearer token can't be used for anything else.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthRequest"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Success result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuthRequest": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "token_type": {
                "$ref": "#/components/schemas/TokenType"
              },
              "bind_to": {
                "$ref": "#/components/schemas/BindToPrincipal"
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethod"
          }
        ]
      },
      "AuthResponse": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "token_type": {
                "$ref": "#/components/schemas/TokenType"
              },
              "expires_in": {
                "type": "integer",
                "minimum": 0,
                "maximum": 4294967295
              },
              "access_token": {
                "type": "string",
                "description": "Token value that the client should subsequently pass in Authorization header."
              },
              "entity_id": {
                "type": "string",
                "format": "uuid"
              },
              "challenge": {
                "$ref": "#/components/schemas/U2fMfaChallengeResponse"
              },
              "fido2_assertion_options": {
                "$ref": "#/components/schemas/PublicKeyCredentialRequestOptions"
              },
              "allowed_mfa_methods": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MfaAuthMethod"
                },
                "nullable": true
              }
            },
            "required": [
              "token_type",
              "expires_in",
              "entity_id"
            ]
          }
        ]
      },
      "TokenType": {
        "type": "string",
        "enum": [
          "Bearer",
          "Cookie"
        ]
      },
      "BindToPrincipal": {
        "description": "A security principal that a session can be bound to.\nEg: When app-1 creates a session that can be validated against app-2's credentials,\napp-1 specifies app-2's ID in `auth` request body like below:\n{\n\"token_type\":\"Bearer\",\n\"bind_to\" : {\n\"app\":\"<app-2's ID>\"\n}\n}\nThis is particularly useful when session token generated using certificate auth of one app needs to be used by another app.",
        "oneOf": [
          {
            "title": "BindToPrincipalVariantApp",
            "type": "object",
            "properties": {
              "app": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "app"
            ]
          }
        ]
      },
      "AuthRequestMethod": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/AuthRequestMethodVariantSamlResponse"
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodVariantOauthAuthCode"
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodVariantLdapBasicAuth"
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodVariantAuthByAppName"
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodVariantAwsIam"
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodVariantPassword"
          }
        ],
        "discriminator": {
          "propertyName": "method",
          "mapping": {
            "saml-response": "AuthRequestMethodVariantSamlResponse",
            "oauth-auth-code": "AuthRequestMethodVariantOauthAuthCode",
            "ldap-basic-auth": "AuthRequestMethodVariantLdapBasicAuth",
            "auth-by-app-name": "AuthRequestMethodVariantAuthByAppName",
            "aws-iam": "AuthRequestMethodVariantAwsIam",
            "password": "AuthRequestMethodVariantPassword"
          }
        }
      },
      "U2fMfaChallengeResponse": {
        "allOf": [
          {
            "type": "object",
            "description": "A challenge used for multi-factor authentication.",
            "properties": {
              "u2f_challenge": {
                "type": "string"
              },
              "u2f_keys": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/U2fRegisteredKey"
                }
              }
            },
            "required": [
              "u2f_challenge",
              "u2f_keys"
            ]
          }
        ]
      },
      "PublicKeyCredentialRequestOptions": {
        "allOf": [
          {
            "type": "object",
            "description": "<https://www.w3.org/TR/webauthn-2/#dictionary-assertion-options>",
            "properties": {
              "challenge": {
                "$ref": "#/components/schemas/Base64UrlSafe"
              },
              "timeout": {
                "type": "integer",
                "nullable": true,
                "description": "The time for which response from the authenticator\nwould be awaited. This should only be a hint as per the spec.\nThis is in milliseconds."
              },
              "rpId": {
                "type": "string",
                "nullable": true,
                "description": "This optional member specifies the relying party identifier\nclaimed by the caller. If omitted, its value will be the\nCredentialsContainer object’s relevant settings object's\norigin's effective domain."
              },
              "allowCredentials": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PublicKeyCredentialDescriptor"
                },
                "nullable": true,
                "description": "This OPTIONAL member contains a list of [PublicKeyCredentialDescriptor]\nobjects representing public key credentials acceptable to the caller,\nin descending order of the caller’s preference (the first item in the\nlist is the most preferred credential, and so on down the list)."
              },
              "userVerification": {
                "$ref": "#/components/schemas/UserVerificationRequirement"
              },
              "extensions": {
                "$ref": "#/components/schemas/AuthenticationExtensionsClientInputs"
              }
            },
            "required": [
              "challenge"
            ]
          }
        ]
      },
      "MfaAuthMethod": {
        "oneOf": [
          {
            "title": "MfaAuthMethodVariantFido2",
            "type": "object",
            "properties": {
              "Fido2": {
                "$ref": "#/components/schemas/MfaAuthMethodFido2"
              }
            },
            "required": [
              "Fido2"
            ]
          }
        ]
      },
      "AuthRequestMethodVariantSamlResponse": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "saml-response"
                ]
              }
            },
            "required": [
              "method"
            ]
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodSamlResponse"
          }
        ]
      },
      "AuthRequestMethodVariantOauthAuthCode": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "oauth-auth-code"
                ]
              }
            },
            "required": [
              "method"
            ]
          },
          {
            "$ref": "#/components/schemas/OauthCodeData"
          }
        ]
      },
      "AuthRequestMethodVariantLdapBasicAuth": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "ldap-basic-auth"
                ]
              }
            },
            "required": [
              "method"
            ]
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodLdapBasicAuth"
          }
        ]
      },
      "AuthRequestMethodVariantAuthByAppName": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "auth-by-app-name"
                ]
              }
            },
            "required": [
              "method"
            ]
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodAuthByAppName"
          }
        ]
      },
      "AuthRequestMethodVariantAwsIam": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "aws-iam"
                ]
              }
            },
            "required": [
              "method"
            ]
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodAwsIam"
          }
        ]
      },
      "AuthRequestMethodVariantPassword": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "password"
                ]
              }
            },
            "required": [
              "method"
            ]
          },
          {
            "$ref": "#/components/schemas/AuthRequestMethodPassword"
          }
        ]
      },
      "U2fRegisteredKey": {
        "allOf": [
          {
            "type": "object",
            "description": "Description of a registered U2F device.",
            "properties": {
              "keyHandle": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            },
            "required": [
              "keyHandle",
              "version"
            ]
          }
        ]
      },
      "Base64UrlSafe": {
        "type": "string",
        "format": "byte"
      },
      "PublicKeyCredentialDescriptor": {
        "allOf": [
          {
            "type": "object",
            "description": "Used to in registration response (telling about existing creds) to prevent\ncreation of duplicate creds on the same authenticator.\nUsed in authentication as the allowed creds.",
            "properties": {
              "type": {
                "$ref": "#/components/schemas/PublicKeyCredentialType"
              },
              "id": {
                "$ref": "#/components/schemas/Base64UrlSafe"
              },
              "transports": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AuthenticatorTransport"
                },
                "nullable": true,
                "description": "Hints by relying party on what transport client should\nuse to communicate with authenticator."
              }
            },
            "required": [
              "type",
              "id"
            ]
          }
        ]
      },
      "UserVerificationRequirement": {
        "description": "https://www.w3.org/TR/webauthn-2/#enum-userVerificationRequirement\nhttps://www.w3.org/TR/webauthn-2/#user-verification",
        "type": "string",
        "enum": [
          "required",
          "preferred",
          "discouraged"
        ]
      },
      "AuthenticationExtensionsClientInputs": {
        "allOf": [
          {
            "type": "object",
            "description": "Extensions for webauthn. For every extension input, an\noutput must be returned if the input was considered.\n\nhttps://www.w3.org/TR/webauthn-2/#dictdef-authenticationextensionsclientinputs",
            "properties": {
              "appidExclude": {
                "type": "string",
                "nullable": true,
                "description": "This extension excludes authenticators during registration\nbased on legacy u2f key handles specified in \"excludeCredentials\".\nIf that key handle was created with that device, it is excluded.\n\nhttps://www.w3.org/TR/webauthn-2/#sctn-appid-exclude-extension"
              },
              "appid": {
                "type": "string",
                "nullable": true,
                "description": "This extension allows RPs that have previously registered a cred\nusing legacy U2F APIs to request an assertion.\n\nhttps://www.w3.org/TR/webauthn-2/#sctn-appid-extension"
              },
              "example.extension.bool": {
                "type": "boolean",
                "nullable": true,
                "description": "Dummy extension used by conformance tests"
              }
            }
          }
        ]
      },
      "MfaAuthMethodFido2": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "challenge": {
                "$ref": "#/components/schemas/PublicKeyCredentialRequestOptions"
              },
              "challenge_token": {
                "type": "string",
                "format": "byte"
              },
              "mfa_devices": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MfaDevice"
                }
              }
            },
            "required": [
              "challenge",
              "challenge_token",
              "mfa_devices"
            ]
          }
        ]
      },
      "AuthRequestMethodSamlResponse": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "nullable": true
              },
              "response": {
                "type": "string"
              }
            },
            "required": [
              "response"
            ]
          }
        ]
      },
      "OauthCodeData": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "idp_id": {
                "type": "string",
                "format": "byte"
              },
              "code": {
                "type": "string"
              },
              "email": {
                "type": "string"
              }
            },
            "required": [
              "idp_id",
              "code",
              "email"
            ]
          }
        ]
      },
      "AuthRequestMethodLdapBasicAuth": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "idp_id": {
                "type": "string",
                "format": "byte"
              },
              "email": {
                "type": "string"
              },
              "password": {
                "type": "string"
              },
              "acct_id": {
                "type": "string",
                "format": "uuid",
                "nullable": true,
                "description": "The account where the IdP is configured. This should\nonly be used if attempting to self-provision into the\naccount. (Self-provisioning may not be possible for\nexisting users; they may need to be manually invited\ninto the account.)"
              }
            },
            "required": [
              "idp_id",
              "email",
              "password"
            ]
          }
        ]
      },
      "AuthRequestMethodAuthByAppName": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "acct_id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string",
                "maxLength": 4096,
                "pattern": "^[^\\n]*[^\\s\\n][^\\n]*$"
              },
              "password": {
                "type": "string"
              }
            },
            "required": [
              "acct_id",
              "name",
              "password"
            ]
          }
        ]
      },
      "AuthRequestMethodAwsIam": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "acct_id": {
                "type": "string",
                "format": "uuid"
              },
              "region": {
                "type": "string"
              },
              "headers": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "required": [
              "acct_id",
              "region",
              "headers"
            ]
          }
        ]
      },
      "AuthRequestMethodPassword": {
        "allOf": [
          {
            "type": "object",
            "description": "Login using a DSM user password and, optionally, a captcha. This is useful\nfor situations where a user is locked out of their DSM account, and wants to\nbecome unlocked.",
            "properties": {
              "email": {
                "type": "string",
                "format": "email",
                "description": "The user's email."
              },
              "password": {
                "type": "string",
                "description": "The user's password."
              },
              "recaptcha_response": {
                "type": "string",
                "nullable": true,
                "description": "The response token after solving a reCAPTCHA successfully."
              }
            },
            "required": [
              "email",
              "password"
            ]
          }
        ]
      },
      "PublicKeyCredentialType": {
        "description": "https://www.w3.org/TR/webauthn-2/#enum-credentialType\n\nThis enum defines valid cred types.",
        "type": "string",
        "enum": [
          "public-key"
        ]
      },
      "AuthenticatorTransport": {
        "description": "Hints by relying party on how client should communicate\nwith the authenticator.\n\nhttps://www.w3.org/TR/webauthn-2/#enum-transport",
        "oneOf": [
          {
            "$ref": "#/components/schemas/AuthenticatorTransportInner"
          },
          {
            "type": "string",
            "description": "Unknown values are stored as spec asks to do so.\nAs per the spec level 3 (which is draft):\n\"The values SHOULD be members of AuthenticatorTransport\nbut Relying Parties SHOULD accept and store unknown values.\"\nSee `[[transports]]` in https://w3c.github.io/webauthn/#iface-authenticatorattestationresponse\n\nLevel 2 also says that but comparitively unclear.\n\"The values SHOULD be members of AuthenticatorTransport but\nRelying Parties MUST ignore unknown values.\"\nSee `[[transports]]` in https://www.w3.org/TR/webauthn-2/#iface-authenticatorattestationresponse"
          }
        ]
      },
      "MfaDevice": {
        "allOf": [
          {
            "type": "object",
            "description": "A FIDO device that may be used for second factor authentication.",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 4096,
                "pattern": "^[^\\n]*[^\\s\\n][^\\n]*$",
                "description": "Name given to the FIDO device."
              },
              "type": {
                "$ref": "#/components/schemas/MfaDeviceType"
              },
              "origin": {
                "type": "string",
                "nullable": true,
                "description": "Origin of the FIDO device."
              }
            },
            "required": [
              "name",
              "type"
            ]
          }
        ]
      },
      "AuthenticatorTransportInner": {
        "description": "See [AuthenticatorTransport] type.",
        "type": "string",
        "enum": [
          "usb",
          "nfc",
          "ble",
          "internal"
        ]
      },
      "MfaDeviceType": {
        "description": "Type of MFA device",
        "type": "string",
        "enum": [
          "U2f",
          "Fido2"
        ]
      }
    }
  }
}
````