REST API Reference

Note: This REST API reference is primarily intended for:
Python backend developers (no SDK available for Python)
Debugging and troubleshooting (understanding what the SDK does under the hood)
Advanced use cases requiring direct server communication
Java backend developers should use the Arculus SDK server-side methods (ArculusFidoServer.callRegisterBegin(), callRegisterComplete(), etc.) instead of direct REST API calls. The SDK abstracts these endpoints and provides better error handling, session management, and future compatibility.

This document provides the complete API reference for the Arculus FIDO2 Server authentication endpoints.

Base URL

https://your-arculus-fido2-server.com

Note: All FIDO2 API endpoints are prefixed with /fidoapi/. The base URL should not include /api in the path.

Authentication Flow Overview

The FIDO2 authentication process consists of two main flows:

Registration (Attestation): Creating a new credential
Authentication (Assertion): Verifying an existing credential

Each flow requires two API calls: begin and complete.

Registration:   attestation/options -> attestation/result
Authentication: assertion/options  -> assertion/result

Endpoints

Registration Endpoints

POST /fidoapi/certify/attestation/options

Begin FIDO2 Registration. This endpoint initiates the credential creation process.

Alias: POST /fidoapi/register/begin

Request Body

Field

Type

Required

Description

username

string

Yes

Unique identifier for the user

displayName

string

Yes

Human-readable name for display

userVerification

string

preferred, required, or discouraged

attestation

string

none, direct, or indirect

attachment

string

platform, cross-platform, or all

algorithms

array

Array of algorithm strings (e.g., ["es256", "rs256"])

discoverable_credential

string

preferred, required, or discouraged

authenticatorSelection

object

Authenticator selection criteria (see below)

keypair

object

Optional device metadata

authenticatorSelection object (optional):

Field

Type

Description

requireResidentKey

boolean

If true, sets residentKey to "preferred" in response

userVerification

string

Override user verification requirement

Example Request

{
  "username": "[email protected]",
  "displayName": "John Doe",
  "userVerification": "preferred",
  "attestation": "none",
  "attachment": "cross-platform",
  "algorithms": ["es256", "rs256"],
  "discoverable_credential": "preferred"
}

Success Response (200)

{
  "status": "ok",
  "errorMessage": "",
  "challenge": "base64url-encoded-challenge",
  "rp": {
    "id": "example.com",
    "name": "Example Service"
  },
  "user": {
    "id": "base64url-encoded-user-id",
    "name": "[email protected]",
    "displayName": "John Doe"
  },
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -7 },
    { "type": "public-key", "alg": -257 }
  ],
  "authenticatorSelection": {
    "requireResidentKey": false,
    "residentKey": "preferred",
    "userVerification": "preferred"
  },
  "attestation": "none",
  "excludeCredentials": [],
  "extensions": {},
  "tokenBinding": {
    "status": "not-supported"
  }
}

POST /fidoapi/certify/attestation/result

Finalize FIDO2 Registration. This endpoint completes credential creation after the authenticator response.

Alias: POST /fidoapi/register/complete

Request Body

Field

Type

Required

Description

type

string

Yes

Must be public-key

id

string

Yes

Base64URL-encoded credential ID

rawId

string

Yes

Base64URL-encoded raw credential ID

authenticatorAttachment

string

platform or cross-platform

response

object

Yes

Authenticator response object

response.clientDataJSON

string

Yes

Base64URL-encoded client data

response.attestationObject

string

Yes

Base64URL-encoded attestation

response.transports

array

Array of transport strings

clientExtensionResults

object

Extension results

Example Request

{
  "type": "public-key",
  "id": "base64url-credential-id",
  "rawId": "base64url-raw-id",
  "authenticatorAttachment": "cross-platform",
  "response": {
    "clientDataJSON": "base64url-encoded-client-data",
    "attestationObject": "base64url-encoded-attestation-object",
    "transports": ["nfc", "usb"]
  },
  "clientExtensionResults": {}
}

Success Response (200)

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

Authentication Endpoints

POST /fidoapi/certify/assertion/options

Begin FIDO2 Assertion. This endpoint initiates the authentication process.

Alias: POST /fidoapi/authenticate/begin

Request Body

Field

Type

Required

Description

username

string

Yes

Username to authenticate

userVerification

string

preferred, required, or discouraged

Example Request

{
  "username": "[email protected]",
  "userVerification": "preferred"
}

Success Response (200)

{
  "status": "ok",
  "errorMessage": "",
  "challenge": "base64url-encoded-challenge",
  "rpId": "example.com",
  "allowCredentials": [
    {
      "type": "public-key",
      "id": "base64url-credential-id"
    }
  ],
  "userVerification": "preferred",
  "extensions": {}
}

POST /fidoapi/certify/assertion/result

Complete FIDO2 Assertion. This endpoint verifies the authenticator signature.

Alias: POST /fidoapi/authenticate/complete

Request Body

Field

Type

Required

Description

type

string

Yes

Must be public-key

id

string

Yes

Base64URL-encoded credential ID

rawId

string

Yes

Base64URL-encoded raw credential ID

authenticatorAttachment

string

platform or cross-platform

response

object

Yes

Authenticator response object

response.clientDataJSON

string

Yes

Base64URL-encoded client data

response.authenticatorData

string

Yes

Base64URL-encoded authenticator data

response.signature

string

Yes

Base64URL-encoded signature

response.userHandle

string

Base64URL-encoded user handle

Example Request

{
  "type": "public-key",
  "id": "base64url-credential-id",
  "rawId": "base64url-raw-id",
  "authenticatorAttachment": "cross-platform",
  "response": {
    "clientDataJSON": "base64url-encoded-client-data",
    "authenticatorData": "base64url-encoded-auth-data",
    "signature": "base64url-encoded-signature",
    "userHandle": "base64url-encoded-user-handle"
  }
}

Success Response (200)

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

Test Endpoints

GET /fidoapi/test

Test if the FIDO API is available and correctly configured.

Response

FidoAPI enabled

GET /fidoapi/testmongo

Test if MongoDB connection is available.

Response

Test Mongo: 7.0.5
Server status: {'ok': 1.0}

Administrative Endpoints

GET /status

Health check and status dashboard.

Response: HTML status page

GET /getversion

Returns server version information.

Response: HTML page with version details

GET / (Root)

Server main dashboard (requires authentication).

Response: HTML dashboard page

User Management API

The User API (/userapi/*) is protected by Basic Authentication by default.

Default credentials (configurable via server options):

Username: redpath
Password: password

To disable authentication, start the server with --auth off.

GET /userapi

User management dashboard.

Response: HTML dashboard page

GET /userapi/manageusers

User administration endpoint with query parameters.

Query Parameters

Parameter

Type

Description

filter

string

Filter users (supports wildcards, e.g., fil*)

device

string

Device name filter

type

string

Operation type (see below)

Type Values

Type

Description

list

List users matching filter

deluser

Delete user

deldevice

Delete specific device

disableall

Disable all credentials for user

enableall

Enable all credentials for user

disabledevice

Disable specific device

enabledevice

Enable specific device

Example Requests

# List a specific user
curl -X GET "http://localhost:5001/userapi/[email protected]&type=list"

# List users matching pattern
curl -X GET "http://localhost:5001/userapi/manageusers?filter=fil*&type=list"

# Delete a specific device
curl -X GET "http://localhost:5001/userapi/manageusers?filter=iPhoneRedpath&device=name&type=deldevice"

# Delete a user
curl -X GET "http://localhost:5001/userapi/[email protected]&type=deluser"

# Disable all credentials for a user
curl -X GET "http://localhost:5001/userapi/[email protected]&type=disableall"

# Enable all credentials for a user
curl -X GET "http://localhost:5001/userapi/[email protected]&type=enableall"

Example Response (list)

[
  {
    "user": "[email protected]",
    "credentials": [
      {
        "deviceinfo": "my Android",
        "serial": "Y9CO-IGZB-4VE0-8QW2",
        "disabled": "off"
      }
    ]
  }
]

GET /userapi/aaguid

Get the AAGUID whitelist.

Response

3F59672F20AA4AFEB6F47E5E916B6D9

Note: The AAGUID filtering feature must be enabled with --aaguid on.

GET /userapi/invoice

Generate invoice data for billing.

Query Parameters

Parameter

Type

Description

date

string

Date in YYYY-MM-DD format (default: today)

invoicelog

string

Set to yes to log the invoice

Example Requests

# Get today's invoice
curl -X GET "http://localhost:5001/userapi/invoice"

# Get invoice for specific date
curl -X GET "http://localhost:5001/userapi/invoice?date=2024-07-11"

# Get invoice and log it
curl -X GET "http://localhost:5001/userapi/invoice?invoicelog=yes&date=2024-07-11"

Response

{
  "database": "ok",
  "count": 37,
  "deleted": 36,
  "disabled": 0,
  "enable": 0,
  "serverid": "REDPATH-30Dec2024"
}

GET /userapi/invoiceest

Estimate invoice generation time.

Response

{
  "status": "ok",
  "data": "1000"
}

POST /userapi/upload

Upload a list of users to query.

Request: multipart/form-data with file

Response

{
  "status": true,
  "statuscode": 200,
  "data": [...]
}

GET /userapi/deletelistusers

Delete users from an uploaded list (dashboard page).

Response: HTML interface for bulk user deletion

Request Headers

All API requests should include:

Content-Type: application/json

Multi-Tenant Support

For multi-tenant deployments, specify the relying party using the X-ArculusFido-RelyingParty header:

X-ArculusFido-RelyingParty: example.com

Note: The header value should be a domain name (e.g., example.com), not a full URL. The server will extract the hostname if a full URL is provided.

Session Management

Important: Session cookies are critical for FIDO2 operations. The registration and authentication flows use session cookies to maintain state between the begin and complete endpoints.

Without proper cookie handling:

The "complete" call cannot find the challenge from the "begin" call
You will receive "Session expired" (E0024R) errors
The authentication or registration flow will fail

Ensure your client:

Stores cookies from the "begin" response (check Set-Cookie header or enable automatic cookie handling)
Sends cookies with the "complete" request (include Cookie header or use credentials: 'include' in fetch)

Session cookies are required for the complete endpoints to validate the challenge and user context from the corresponding begin request. For more details, see Session Cookie Management in the Authenticator Lifecycle documentation.

Error Responses

All endpoints return consistent error responses. For detailed error codes and handling, see 2.7 Error Codes Reference.

Error Response Format:

{
  "status": "ok" | "failed" | "false",
  "errorMessage": "Error code and description (empty string on success)",
  "statuscode": "HTTP status code (as string, optional)"
}

Note: The status field may be "failed" or "false" depending on the error type. Session-related errors typically return "status": "false".

CORS Support

The server supports Cross-Origin Resource Sharing (CORS). Ensure your client includes:

credentials: 'include'

This is required for session cookie management during the registration and authentication flows.

Data Format Reference

Base64URL Encoding

All binary data in the API uses Base64URL encoding (RFC 4648):

Standard Base64 with - instead of +
Standard Base64 with _ instead of /
No padding characters (=)

Example Encoding:

// Encode
const base64url = btoa(String.fromCharCode(...bytes))
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=/g, '');

// Decode
const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
const padding = '=='.slice(0, (4 - base64.length % 4) % 4);
const bytes = atob(base64 + padding);

COSE Algorithm Identifiers

Public key credential parameters use COSE algorithm identifiers:

Algorithm

COSE ID

Description

ES256

-7

ECDSA with SHA-256

RS256

-257

RSASSA-PKCS1-v1_5 with SHA-256

EdDSA

-8

Edwards-curve Digital Signature

Reference: IANA COSE Algorithm Registry

AAGUID Format

The Authenticator Attestation GUID (AAGUID) is a 16-byte identifier for authenticator models.

Format: UUID string with hyphens

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example:

2fc0579f-8113-47ea-b116-bb5a8db9202a

A null AAGUID (all zeros) indicates the authenticator does not provide model identification:

00000000-0000-0000-0000-000000000000

Credential Protection Levels

The credProtect extension provides additional credential security:

Level

Name

Description

User Verification Optional

Credentials usable without verification; may be discoverable

UV Optional, Non-Discoverable

No verification required; credential not enumerable

User Verification Required

Verification required; credential protected

High Protection

Maximum security; additional restrictions apply

PreviousPython Sample Applications NextBackend Integration Helpers

Last updated 1 month ago

hashtagBase URL

hashtagAuthentication Flow Overview

hashtagEndpoints

hashtagRegistration Endpoints

hashtagPOST /fidoapi/certify/attestation/options

hashtagPOST /fidoapi/certify/attestation/result

hashtagAuthentication Endpoints

hashtagPOST /fidoapi/certify/assertion/options

hashtagPOST /fidoapi/certify/assertion/result

hashtagTest Endpoints

hashtagGET /fidoapi/test

hashtagGET /fidoapi/testmongo

hashtagAdministrative Endpoints

hashtagGET /status

hashtagGET /getversion

hashtagGET / (Root)

hashtagUser Management API

hashtagGET /userapi

hashtagGET /userapi/manageusers

hashtagGET /userapi/aaguid

hashtagGET /userapi/invoice

hashtagGET /userapi/invoiceest

hashtagPOST /userapi/upload

hashtagGET /userapi/deletelistusers

hashtagRequest Headers

hashtagMulti-Tenant Support

hashtagSession Management

hashtagError Responses

hashtagCORS Support

hashtagData Format Reference

hashtagBase64URL Encoding

hashtagCOSE Algorithm Identifiers

hashtagAAGUID Format

hashtagCredential Protection Levels

Base URL

Authentication Flow Overview

Endpoints

Registration Endpoints

POST /fidoapi/certify/attestation/options

POST /fidoapi/certify/attestation/result

Authentication Endpoints

POST /fidoapi/certify/assertion/options

POST /fidoapi/certify/assertion/result

Test Endpoints

GET /fidoapi/test

GET /fidoapi/testmongo

Administrative Endpoints

GET /status

GET /getversion

GET / (Root)

User Management API

GET /userapi

GET /userapi/manageusers

GET /userapi/aaguid

GET /userapi/invoice

GET /userapi/invoiceest

POST /userapi/upload

GET /userapi/deletelistusers

Request Headers

Multi-Tenant Support

Session Management

Error Responses

CORS Support

Data Format Reference

Base64URL Encoding

COSE Algorithm Identifiers

AAGUID Format

Credential Protection Levels