> ## 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. # Get credential creation options as per the given request. > The response of this API needs to be used with relevant API for the protocol. For U2F, it is `u2f.register()`. For FIDO2, it is `navigator.credentials.create()`. ## OpenAPI ````json POST /sys/v1/session/config_2fa/new_challenge { "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/config_2fa/new_challenge": { "post": { "operationId": "MfaNewChallenge", "tags": [ "Fido" ], "security": [ { "bearerToken": [] }, { "apiKeyAuth": [] } ], "summary": "Get credential creation options as per the given request.", "description": "The response of this API needs to be used with relevant API\nfor the protocol.\nFor U2F, it is `u2f.register()`.\nFor FIDO2, it is `navigator.credentials.create()`.", "parameters": [ { "$ref": "#/components/parameters/MfaChallengeParams" } ], "responses": { "2XX": { "description": "Success result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaChallengeResponse" } } } } } } } }, "components": { "parameters": { "MfaChallengeParams": { "in": "query", "name": "MfaChallengeParams", "schema": { "$ref": "#/components/schemas/MfaChallengeParams" }, "explode": true } }, "schemas": { "MfaChallengeResponse": { "oneOf": [ { "$ref": "#/components/schemas/U2fMfaChallengeResponse" }, { "$ref": "#/components/schemas/Fido2MfaChallengeResponse" } ] }, "MfaChallengeParams": { "allOf": [ { "type": "object", "description": "Params for Mfa challenge.", "properties": { "protocol": { "$ref": "#/components/schemas/MfaProtocol" } }, "required": [ "protocol" ] } ] }, "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" ] } ] }, "Fido2MfaChallengeResponse": { "description": "Fido2 options when requesting assertion or attestation to a device", "oneOf": [ { "$ref": "#/components/schemas/PublicKeyCredentialCreationOptions" }, { "$ref": "#/components/schemas/PublicKeyCredentialRequestOptions" } ] }, "MfaProtocol": { "description": "Protocols for MFA.", "type": "string", "enum": [ "u2f", "fido2" ] }, "U2fRegisteredKey": { "allOf": [ { "type": "object", "description": "Description of a registered U2F device.", "properties": { "keyHandle": { "type": "string" }, "version": { "type": "string" } }, "required": [ "keyHandle", "version" ] } ] }, "PublicKeyCredentialCreationOptions": { "allOf": [ { "type": "object", "description": "", "properties": { "rp": { "$ref": "#/components/schemas/PublicKeyCredentialEntityForRp" }, "user": { "$ref": "#/components/schemas/PublicKeyCredentialEntityForUser" }, "challenge": { "$ref": "#/components/schemas/Base64UrlSafe" }, "pubKeyCredParams": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialParameters" }, "description": "This member contains information about the desired properties of the\ncredential to be created. The sequence is ordered from most preferred\nto least preferred." }, "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." }, "excludeCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialDescriptor" }, "description": "The existing creds mapped to the current user. This tells\nthe authenticator to not create multiple creds for the same\nuser.\nNOTE: This isn't for U2F authenticators. For that, `appidExclude`\nneeds to be set instead." }, "authenticatorSelection": { "$ref": "#/components/schemas/AuthenticatorSelectionCriteria" }, "attestation": { "$ref": "#/components/schemas/AttestationConveyancePreference" }, "extensions": { "$ref": "#/components/schemas/AuthenticationExtensionsClientInputs" } }, "required": [ "rp", "user", "challenge", "pubKeyCredParams", "excludeCredentials", "attestation" ] } ] }, "PublicKeyCredentialRequestOptions": { "allOf": [ { "type": "object", "description": "", "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" ] } ] }, "PublicKeyCredentialEntityForRp": { "allOf": [ { "description": "https://www.w3.org/TR/webauthn-2/#dictionary-pkcredentialentity", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the entity." }, "entity": { "$ref": "#/components/schemas/PublicKeyCredentialRpEntity" } } } ] }, "PublicKeyCredentialEntityForUser": { "allOf": [ { "description": "https://www.w3.org/TR/webauthn-2/#dictionary-pkcredentialentity", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the entity." }, "entity": { "$ref": "#/components/schemas/PublicKeyCredentialUserEntity" } } } ] }, "Base64UrlSafe": { "type": "string", "format": "byte" }, "PublicKeyCredentialParameters": { "allOf": [ { "type": "object", "description": "https://www.w3.org/TR/webauthn-2/#dictionary-credential-params", "properties": { "type": { "$ref": "#/components/schemas/PublicKeyCredentialType" }, "alg": { "$ref": "#/components/schemas/COSEAlgorithmIdentifier" } }, "required": [ "type", "alg" ] } ] }, "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" ] } ] }, "AuthenticatorSelectionCriteria": { "allOf": [ { "type": "object", "description": "Parameters for deciding which authenticators should be selected.\n\n", "properties": { "authenticatorAttachment": { "$ref": "#/components/schemas/AuthenticatorAttachment" }, "residentKey": { "$ref": "#/components/schemas/ResidentKeyRequirement" }, "requireResidentKey": { "type": "boolean", "nullable": true, "description": "Exists for backcompat with webauthn level 1.\nBy default it is false and should be set to true\nif `residentKey` is set to `required`." }, "userVerification": { "$ref": "#/components/schemas/UserVerificationRequirement" } } } ] }, "AttestationConveyancePreference": { "description": "\n\n\nIf you really want to understand attestation, read the following:\n\n\n\nThis enum just specified how the attestation should be conveyed\nto the RP. You can see doc of the individual variants to understand\nvarious ways.", "type": "string", "enum": [ "none", "indirect", "direct", "enterprise" ] }, "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" } } } ] }, "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" ] }, "PublicKeyCredentialRpEntity": { "allOf": [ { "type": "object", "description": "", "properties": { "id": { "type": "string", "nullable": true, "description": "A unique identifier for the Relying Party entity, which sets the RP ID.\n\n" } } } ] }, "PublicKeyCredentialUserEntity": { "allOf": [ { "type": "object", "description": "", "properties": { "id": { "$ref": "#/components/schemas/Base64UrlSafe" }, "displayName": { "type": "string", "description": "Human friendly name intended only for display." } }, "required": [ "id", "displayName" ] } ] }, "PublicKeyCredentialType": { "description": "https://www.w3.org/TR/webauthn-2/#enum-credentialType\n\nThis enum defines valid cred types.", "type": "string", "enum": [ "public-key" ] }, "COSEAlgorithmIdentifier": { "description": "https://www.w3.org/TR/webauthn-2/#typedefdef-cosealgorithmidentifier\n\nSigning algorithms from [IANA COSE Algorithms registry]\nthat are supported on DSM side for verifying signed messages\nfrom authenticator.\n\n[IANA COSE Algorithms registry]: https://www.iana.org/assignments/cose/cose.xhtml#algorithms", "type": "string", "enum": [ "Es256" ] }, "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" } ] }, "AuthenticatorAttachment": { "description": "", "type": "string", "enum": [ "platform", "cross-platform" ] }, "ResidentKeyRequirement": { "description": "\n\nTells Relying Party's requirement about client side discoverable\ncreds (formely known as resident keys).\nIf client side discoverable creds are there, it means that the\nauthenticator is self-sufficient in identifying the user. If this\nisn't the case, the user needs to login first so that the server\ncan identify the user and help send `allowCredentials` to authenticator.\n\nThis is mostly meant for [username-less] authentication (which we don't\nsupport in DSM). We support 2FA where we already know about the logged\nin user.\n\n[username-less]: ", "type": "string", "enum": [ "discouraged", "preferred", "required" ] }, "AuthenticatorTransportInner": { "description": "See [AuthenticatorTransport] type.", "type": "string", "enum": [ "usb", "nfc", "ble", "internal" ] } } } } ````