SDK API Reference

This page provides a comprehensive reference of all SDK methods available across iOS, Android, Desktop (Java), and Web (JavaScript) platforms. For detailed usage examples and integration guides, see the platform-specific SDK pages.

iOS SDK (Swift)

Client-Direct Methods

registerUser

Registers a new FIDO2 credential with the FIDO2 server.

public func registerUser(
    fidoServer: ArculusFidoServer,
    pin: String,
    username: String,
    displayName: String,
    relyingParty: String,
    resetDevice: Bool = false,
    registrationInfo: String? = nil
) async -> String

Parameters:

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
relyingParty	String	Relying party ID (domain)
resetDevice	Bool	If true, resets card and sets PIN
registrationInfo	String?	Optional device metadata JSON

Returns: JSON string with status and response details.

authenticateUser

Authenticates a user using an existing FIDO2 credential.

public func authenticateUser(
    fidoServer: ArculusFidoServer,
    pin: String,
    username: String,
    displayName: String,
    relyingParty: String
) async -> String

Parameters:

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	Card PIN
username	String	User identifier
displayName	String	Human-readable name
relyingParty	String	Relying party ID (must match registration)

Returns: JSON string with status and response details.

Backend-Proxied Methods

registerCardOnly

Performs card registration only (no server communication). Used in backend-proxied deployments.

public func registerCardOnly(
    pin: String,
    username: String,
    displayName: String,
    rpId: String,
    challenge: String,
    origin: String
) async throws -> String

Parameters:

Parameter	Type	Description
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
rpId	String	Relying party ID (domain)
challenge	String	Base64-encoded challenge from backend's /register/begin response
origin	String	Origin URL for clientDataJSON (typically FIDO2 server URL)

Returns: JSON string containing card response data to send to backend.

Note: Unlike authenticateCardOnly(), this method takes challenge and origin directly rather than an optionsResponse object.

authenticateCardOnly

Performs card authentication only (no server communication). Used in backend-proxied deployments.

public func authenticateCardOnly(
    pin: String,
    username: String,
    rpId: String,
    optionsResponse: ArculusFidoOptionsAuthorizationResponse
) async throws -> String

Parameters:

Parameter	Type	Description
pin	String	Card PIN
username	String	User identifier
rpId	String	Relying party ID (must match registration)
optionsResponse	ArculusFidoOptionsAuthorizationResponse	Pre-constructed options response containing challenge from backend

Returns: JSON string containing card response data to send to backend.

Note: Unlike registerCardOnly(), this method uses an optionsResponse object that must be constructed from the backend's response.

PIN Management Methods

setPin

Resets the card and sets a new PIN. Warning: This erases all credentials on the card.

public func setPin(pin: String) async throws -> String

Parameters:

Parameter	Type	Description
pin	String	New 6+ digit PIN

Returns: JSON string with status and response details.

changePin

Changes the PIN while preserving all credentials on the card.

public func changePin(oldPin: String, newPin: String) async -> String

Parameters:

Parameter	Type	Description
oldPin	String	Current PIN
newPin	String	New 6+ digit PIN

Returns: JSON string with status and response details.

Helper Methods

deleteCredentialByCredentialId

Deletes a credential from the card by credential ID. Used for rollback operations.

public func deleteCredentialByCredentialId(
    pin: String,
    credentialId: String
) async throws -> String

Parameters:

Parameter	Type	Description
pin	String	Card PIN
credentialId	String	Credential ID to delete

Returns: JSON string with status and response details.

Android SDK (Java)

Client-Direct Methods

register

Registers a new FIDO2 credential with the FIDO2 server.

public void register(
    ArculusFidoServer fidoServer,
    String pin,
    String username,
    String displayname,
    String relyingParty,
    boolean resetDevice,
    String registrationInfo
)

Parameters:

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayname	String	Human-readable name
relyingParty	String	Relying party ID (domain)
resetDevice	boolean	If true, resets card and sets PIN
registrationInfo	String	Optional device metadata JSON

Callback: Results are returned via ArculusFidoResultCallback.registerResult(String response).

authenticate

Authenticates a user using an existing FIDO2 credential.

public void authenticate(
    ArculusFidoServer fidoServer,
    String pin,
    String username,
    String displayName,
    String relyingParty
)

Parameters:

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	Card PIN
username	String	User identifier
displayName	String	Human-readable name
relyingParty	String	Relying party ID (must match registration)

Callback: Results are returned via ArculusFidoResultCallback.authenticateResult(String response).

Backend-Proxied Methods

registerCardOnly

Performs card registration only (no server communication). Used in backend-proxied deployments.

public String registerCardOnly(
    String pin,
    String username,
    String displayName,
    String rpId,
    String challenge,
    String origin
)

Parameters:

Parameter	Type	Description
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
rpId	String	Relying party ID (domain)
challenge	String	Base64-encoded challenge from backend's /register/begin response
origin	String	Origin URL for clientDataJSON (typically FIDO2 server URL)

Returns: JSON string containing card response data to send to backend.

Note: Unlike authenticateCardOnly(), this method takes challenge and origin directly rather than an optionsResponse object.

authenticateCardOnly

Performs card authentication only (no server communication). Used in backend-proxied deployments.

public String authenticateCardOnly(
    String pin,
    String username,
    String rpId,
    ArculusFidoOptionsAuthorizationResponse optionsResponse
)

Parameters:

Parameter	Type	Description
pin	String	Card PIN
username	String	User identifier
rpId	String	Relying party ID (must match registration)
optionsResponse	ArculusFidoOptionsAuthorizationResponse	Pre-constructed options response containing challenge from backend

Returns: JSON string containing card response data to send to backend.

Note: Unlike registerCardOnly(), this method uses an optionsResponse object that must be constructed from the backend's response.

PIN Management Methods

setPin

Resets the card and sets a new PIN. Warning: This erases all credentials on the card.

public void setPin(String pin)

Parameters:

Parameter	Type	Description
pin	String	New 6+ digit PIN

Callback: Results are returned via ArculusFidoResultCallback.setPinResult(String response).

changePin

Changes the PIN while preserving all credentials on the card.

public void changePin(String oldPin, String newPin)

Parameters:

Parameter	Type	Description
oldPin	String	Current PIN
newPin	String	New 6+ digit PIN

Callback: Results are returned via ArculusFidoResultCallback.changePinResult(String response).

Helper Methods

deleteCredentialByCredentialId

Deletes a credential from the card by credential ID. Used for rollback operations.

public String deleteCredentialByCredentialId(String pin, String credentialId)

Parameters:

Parameter	Type	Description
pin	String	Card PIN
credentialId	String	Credential ID to delete

Returns: JSON string with status and response details.

Desktop SDK (Java)

Client-Direct Methods

register

Registers a new FIDO2 credential with the FIDO2 server.

public String register(
    ArculusFidoServer fidoServer,
    String pin,
    String username,
    String displayName,
    String relyingParty,
    boolean resetDevice,
    String registrationInfo
)

Parameters:

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
relyingParty	String	Relying party ID (domain)
resetDevice	boolean	If true, resets card and sets PIN
registrationInfo	String	Optional device metadata JSON

Returns: JSON string with status and response details.

authenticate

Authenticates a user using an existing FIDO2 credential.

public String authenticate(
    ArculusFidoServer fidoServer,
    String pin,
    String username,
    String displayName,
    String relyingParty
)

Parameters:

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	Card PIN
username	String	User identifier
displayName	String	Human-readable name
relyingParty	String	Relying party ID (must match registration)

Returns: JSON string with status and response details.

Backend-Proxied Methods

registerCardOnly

Performs card registration only (no server communication). Used in backend-proxied deployments.

public String registerCardOnly(
    String pin,
    String username,
    String displayName,
    String relyingParty,
    String challenge,
    String origin
) throws ArculusFidoException

Parameters:

Parameter	Type	Description
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
relyingParty	String	Relying party ID (domain)
challenge	String	Base64-encoded challenge from backend's /register/begin response
origin	String	Origin URL for clientDataJSON (typically FIDO2 server URL)

Returns: JSON string containing card response data to send to backend.

Throws: ArculusFidoException if card operation fails.

Note: Unlike authenticateCardOnly(), this method takes challenge and origin directly rather than an optionsResponse object.

authenticateCardOnly

Performs card authentication only (no server communication). Used in backend-proxied deployments.

public AuthenticateCardSignResponse authenticateCardOnly(
    String pin,
    String username,
    String relyingParty,
    ArculusFidoOptionsAuthorizationResponse optionsResponse
) throws ArculusFidoException

Parameters:

Parameter	Type	Description
pin	String	Card PIN
username	String	User identifier
relyingParty	String	Relying party ID (must match registration)
optionsResponse	ArculusFidoOptionsAuthorizationResponse	Pre-constructed options response containing challenge from backend

Returns: AuthenticateCardSignResponse object containing id, rawId, authdataBase64, and signatureBase64.

Throws: ArculusFidoException if card operation fails.

Note: Unlike registerCardOnly(), this method uses an optionsResponse object that must be constructed from the backend's response.

PIN Management Methods

setPin

Resets the card and sets a new PIN. Warning: This erases all credentials on the card.

public String setPin(String pin)

Parameters:

Parameter	Type	Description
pin	String	New 6+ digit PIN

Returns: JSON string with status and response details.

changePin

Changes the PIN while preserving all credentials on the card.

public String changePin(String oldPin, String newPin)

Parameters:

Parameter	Type	Description
oldPin	String	Current PIN
newPin	String	New 6+ digit PIN

Returns: JSON string with status and response details.

Reader Management Methods

listReaders

Lists all available PC/SC-compatible NFC readers.

public List<String> listReaders()

Returns: List of reader names.

selectReader

Selects a specific reader by name.

public void selectReader(String readerName)

Parameters:

Parameter	Type	Description
readerName	String	Name of the reader to use

Web SDK (JavaScript)

Registration Method

RegisterUser

Registers a new FIDO2 credential with the FIDO2 server.

async function RegisterUser(
  username,      // string: Unique username (typically email)
  displayname,   // string: Display name shown on authenticator
  keypair,       // object|string: Device metadata (optional)
  servlet,       // string: Server URL prefix (empty for same origin)
  parms,         // string: Additional query parameters
  addHeaders     // object: Additional HTTP headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})
)

Parameters:

Parameter	Type	Description
username	string	Unique username (typically email)
displayname	string	Display name shown on authenticator
keypair	object|string	Optional device metadata
servlet	string	Server URL prefix (empty for same origin)
parms	string	Additional query parameters
addHeaders	object	Additional HTTP headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})

Returns: Promise resolving to response object with status, result/error, and statuscode fields.

Note: The SDK parameter is displayname (lowercase 'n'), but JavaScript is case-insensitive for parameter names, so displayName also works.

Authentication Method

AuthenticateUser

Authenticates a user using an existing FIDO2 credential.

async function AuthenticateUser(
  username,      // string: Username to authenticate
  servlet,       // string: Server URL prefix (empty for same origin)
  parms,         // string: Additional query parameters
  addHeaders     // object: Additional HTTP headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})
)

Parameters:

Parameter	Type	Description
username	string	Username to authenticate
servlet	string	Server URL prefix (empty for same origin)
parms	string	Additional query parameters
addHeaders	object	Additional HTTP headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})

Returns: Promise resolving to response object with status, result, jwtToken (if present), and statuscode fields.

ArculusFidoServer Class (All Platforms)

The ArculusFidoServer class is used to configure FIDO2 server connection details for client-direct deployments.

iOS (Swift)

// Basic initialization
let server = ArculusFidoServer(domain: "fido.example.com")

// With custom endpoints
let server = ArculusFidoServer(
    domain: "fido.example.com",
    beginRegistrationPath: "custom/register/begin",
    completeRegistrationPath: "custom/register/complete",
    beginAuthenticationPath: "custom/auth/begin",
    completeAuthenticationPath: "custom/auth/complete"
)

// Set custom headers
server.setRequestProperty(key: "Authorization", value: "Bearer token123")

Properties:

Property	Type	Description
registrationBeginEndpoint	String	Registration options endpoint
registrationCompleteEndpoint	String	Registration result endpoint
authorizationBeginEndpoint	String	Authentication options endpoint
authorizationCompleteEndpoint	String	Authentication result endpoint

Android/Desktop (Java)

// Simple constructor (uses default endpoints)
ArculusFidoServer fidoServer = new ArculusFidoServer("fido.example.com");

// With custom endpoints
ArculusFidoServer fidoServer = new ArculusFidoServer(
    "fido.example.com",
    "custom/registration/begin",
    "custom/registration/complete",
    "custom/authentication/begin",
    "custom/authentication/complete"
);

// Set custom headers
fidoServer.setRequestProperty("Authorization", "Basic dXNlcjpwYXNz");
fidoServer.setRequestProperty("X-API-Key", "your-api-key");

Methods:

Method	Description
setBeginRegistrationPath(path, params)	Set registration options endpoint
setCompleteRegistrationPath(path, params)	Set registration result endpoint
setBeginAuthenticatePath(path, params)	Set authentication options endpoint
setCompleteAuthenticatePath(path, params)	Set authentication result endpoint
setRequestProperty(key, value)	Add custom HTTP header
setDeviceinfo(json)	Set device metadata for registration

Response Format

All SDK methods return responses in JSON format:

Success Response:

{
  "status": "ok",
  "errorMessage": "",
  "responseCode": 200
}

Error Response:

{
  "status": "failed",
  "errorMessage": "Error description",
  "responseCode": 400
}

For detailed error codes, see 2.7 Error Codes.