MFA & Passkeys API Reference

Complete API reference for multi-factor authentication and passkey operations in the Dynamic Swift SDK.

MFA Operations

getUserDevices

Fetch all MFA devices for the authenticated user.

func getUserDevices() async throws -> [MfaDevice]

Returns: Array of MfaDevice objects

Example:

let sdk = DynamicSDK.instance()
let devices = try await sdk.mfa.getUserDevices()

addDevice

Add a new TOTP device for the user.

func addDevice(type: String) async throws -> MfaAddDevice

Parameters:

• type - Device type (e.g., "totp")

Returns: MfaAddDevice containing the secret for authenticator setup

Example:

let sdk = DynamicSDK.instance()
let result = try await sdk.mfa.addDevice(type: "totp")
print("Secret: \(result.secret)")

verifyDevice

Verify a newly added device with a TOTP code.

func verifyDevice(_ code: String, type: String) async throws

Parameters:

• code - The 6-digit TOTP code from the authenticator app
• type - Device type (e.g., "totp")

Example:

let sdk = DynamicSDK.instance()
try await sdk.mfa.verifyDevice("123456", type: "totp")

authenticateDevice

Authenticate an MFA device with a TOTP code.

func authenticateDevice(params: MfaAuthenticateDevice) async throws -> String?

Parameters:

• params - Authentication parameters including code, device ID, and token options

Returns: MFA authentication token (optional)

Example:

let sdk = DynamicSDK.instance()
let mfaToken = try await sdk.mfa.authenticateDevice(
    params: MfaAuthenticateDevice(
        code: "123456",
        deviceId: "device_id",
        createMfaToken: MfaCreateToken(singleUse: false)
    )
)

deleteUserDevice

Delete an MFA device from the user’s account.

func deleteUserDevice(deviceId: String, mfaAuthToken: String) async throws

Parameters:

• deviceId - ID of the device to delete
• mfaAuthToken - MFA authentication token

Example:

let sdk = DynamicSDK.instance()
try await sdk.mfa.deleteUserDevice(
    deviceId: "device_id",
    mfaAuthToken: mfaToken
)

getRecoveryCodes

Retrieve backup recovery codes for the user.

func getRecoveryCodes(generateNewCodes: Bool) async throws -> [String]

Parameters:

• generateNewCodes - Whether to generate new codes or retrieve existing ones

Returns: Array of recovery code strings

Example:

let sdk = DynamicSDK.instance()
let codes = try await sdk.mfa.getRecoveryCodes(generateNewCodes: false)

getNewRecoveryCodes

Generate new recovery codes, invalidating old ones.

func getNewRecoveryCodes() async throws -> [String]

Returns: Array of new recovery code strings

Example:

let sdk = DynamicSDK.instance()
let newCodes = try await sdk.mfa.getNewRecoveryCodes()

// User must acknowledge the new codes
try await sdk.mfa.completeAcknowledgement()

isPendingRecoveryCodesAcknowledgment

Check if recovery codes need acknowledgment.

func isPendingRecoveryCodesAcknowledgment() async throws -> Bool

Returns: Boolean indicating if acknowledgment is pending

Example:

let sdk = DynamicSDK.instance()
let isPending = try await sdk.mfa.isPendingRecoveryCodesAcknowledgment()

completeAcknowledgement

Acknowledge that user has saved their recovery codes.

func completeAcknowledgement() async throws

Example:

let sdk = DynamicSDK.instance()
try await sdk.mfa.completeAcknowledgement()

authenticateRecoveryCode

Authenticate using a recovery code.

func authenticateRecoveryCode(code: MfaAuthenticateRecoveryCode) async throws -> String?

Parameters:

• code - Recovery code and token creation options

Returns: MFA authentication token (optional)

Example:

let sdk = DynamicSDK.instance()
let mfaToken = try await sdk.mfa.authenticateRecoveryCode(
    code: MfaAuthenticateRecoveryCode(
        code: "recovery_code",
        createMfaToken: MfaCreateToken(singleUse: true)
    )
)

Passkey Operations

signIn

Sign in using an existing passkey.

func signIn() async throws -> SdkUser

Returns: SdkUser object for the authenticated user

Example:

let sdk = DynamicSDK.instance()
let user = try await sdk.auth.passkey.signIn()

registerPasskey

Register a new passkey for the authenticated user.

func registerPasskey() async throws -> PasskeyRegistrationResult

Returns: Registration result

Example:

let sdk = DynamicSDK.instance()
_ = try await sdk.passkeys.registerPasskey()

getPasskeys

Fetch all passkeys registered for the user.

func getPasskeys() async throws -> [UserPasskey]

Returns: Array of UserPasskey objects

Example:

let sdk = DynamicSDK.instance()
let passkeys = try await sdk.passkeys.getPasskeys()

authenticatePasskeyMFA

Authenticate with a passkey for MFA.

func authenticatePasskeyMFA(
    createMfaToken: MfaCreateToken,
    relatedOriginRpId: String?
) async throws -> PasskeyMfaResponse

Parameters:

• createMfaToken - Token creation options
• relatedOriginRpId - Optional Relying Party ID (RP ID) for authenticating from a related origin. The canonical form is a bare hostname such as my.example.com; a full origin like https://my.example.com is also accepted and resolves to the same RP ID. It must match the rpId the credential was registered under.

Returns: PasskeyMfaResponse containing JWT token

Example:

let sdk = DynamicSDK.instance()
let response = try await sdk.passkeys.authenticatePasskeyMFA(
    createMfaToken: MfaCreateToken(singleUse: true),
    relatedOriginRpId: nil
)
print("Token: \(response.jwt ?? "nil")")

deletePasskey

Delete a passkey from the user’s account.

func deletePasskey(_ request: DeletePasskeyRequest) async throws

Parameters:

• request - Delete request containing the passkey ID

Example:

let sdk = DynamicSDK.instance()
try await sdk.passkeys.deletePasskey(
    DeletePasskeyRequest(passkeyId: "passkey_id")
)

Data Types

MfaDevice

Represents an MFA device.

struct MfaDevice {
    let id: String?
    let type: MfaDeviceType?
    let createdAt: String?
}

MfaAddDevice

Result of adding a new MFA device.

struct MfaAddDevice {
    let secret: String
}

MfaAuthenticateDevice

Parameters for device authentication.

struct MfaAuthenticateDevice {
    let code: String
    let deviceId: String
    let createMfaToken: MfaCreateToken
}

MfaCreateToken

Token creation options for MFA.

struct MfaCreateToken {
    let singleUse: Bool
}

MfaAuthenticateRecoveryCode

Parameters for recovery code authentication.

struct MfaAuthenticateRecoveryCode {
    let code: String
    let createMfaToken: MfaCreateToken
}

UserPasskey

Represents a user’s passkey.

struct UserPasskey {
    let id: String
    let createdAt: Date
    let lastUsedAt: Date?
    let isDefault: Bool?
}

DeletePasskeyRequest

Request to delete a passkey.

struct DeletePasskeyRequest {
    let passkeyId: String
}

PasskeyMfaResponse

Response from passkey MFA authentication.

struct PasskeyMfaResponse {
    let jwt: String?
}

Error Handling

All MFA and passkey operations can throw errors. Handle them appropriately:

let sdk = DynamicSDK.instance()

do {
    let devices = try await sdk.mfa.getUserDevices()
} catch {
    print("Error: \(error.localizedDescription)")
}

See Also

• MFA Guide - Complete guide to implementing MFA
• Passkey Authentication - Passkey setup and usage
• Authentication Guide - Basic authentication methods