# SurePassID REST API Reference Guide

**Version:** 2025.4  
**Document Purpose:** Complete API specification for verification testing of rewritten implementations

---

## Table of Contents

1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Common Request/Response Structure](#common-requestresponse-structure)
4. [Enumerations Reference](#enumerations-reference)
5. [API Endpoints](#api-endpoints)
   - [Authentication APIs](#authentication-apis)
   - [User Management APIs](#user-management-apis)
   - [Token/Device Management APIs](#tokendevice-management-apis)
   - [Push Authentication APIs](#push-authentication-apis)
   - [Session Management APIs](#session-management-apis)
   - [FIDO U2F APIs](#fido-u2f-apis)
   - [System APIs](#system-apis)
   - [Sync APIs](#sync-apis)
6. [Error Codes Reference](#error-codes-reference)
7. [API Permissions Reference](#api-permissions-reference)

---

## Overview

The SurePassID REST API provides programmatic access to multi-factor authentication services. All API requests use JSON format and are processed through the `/api/ServerProxy.ashx` endpoint.

### Base URL
```
https://<server>/api/ServerProxy.ashx
```

### Content Type
```
Content-Type: application/json
```

---

## Authentication

Most API endpoints require authentication using an API Key pair. The credentials are passed in the request body.

### Authentication Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `spAccountLoginName` | string | Yes* | API Key ID |
| `spAccountLoginKey` | string | Yes* | API Key Secret |

*Required for all endpoints except: `get_system_time`, `provision_oath_device`, `provision_device`, `provision_push_device` (when direct provisioning is enabled)

### Example Authentication
```json
{
    "type": "find_user",
    "spAccountLoginName": "api-key-id-here",
    "spAccountLoginKey": "api-key-secret-here",
    "username": "john.doe"
}
```

---

## Common Request/Response Structure

### Standard Request Format
```json
{
    "type": "<api_type>",
    "spAccountLoginName": "<api_key_id>",
    "spAccountLoginKey": "<api_key_secret>",
    // Additional parameters specific to the API
}
```

### Standard Response Format

#### Success Response
```json
{
    "type": "<api_type>",
    "errorCode": 0,
    "errorMessage": "OK"
    // Additional response data specific to the API
}
```

#### Error Response
```json
{
    "type": "<api_type>",
    "errorCode": <error_code>,
    "errorMessage": "<error_description>"
}
```

---

## Enumerations Reference

### DeviceTypesEnum
| Value | Name | Description |
|-------|------|-------------|
| -1 | None | No device type |
| 0 | FOB | Hardware FOB token |
| 1 | Desktop | Desktop software token |
| 4 | ElectronicCard | Electronic card token |
| 5 | SmartCard | Smart card token |
| 6 | MatrixCard | Matrix card token |
| 7 | CellPhoneSMS | SMS-based OTP |
| 8 | GoogleAuthenticator | Google Authenticator compatible |
| 9 | SurePassAuthenticatorMobile | SurePassID Mobile Authenticator |
| 10 | CellPhoneVoice | Voice call OTP |
| 11 | CellPhoneVoiceNoOTP | Voice call confirmation (no OTP) |
| 12 | FIDO | FIDO security key |
| 13 | NymiBand | Nymi Band biometric |
| 14 | Treo | Treo device |

### OTPTypesEnum
| Value | Name | Description |
|-------|------|-------------|
| 0 | Event | HOTP (Event-based) |
| 1 | Time | TOTP (Time-based) |
| 2 | TimeAndPassword | TOTP with PIN |
| 3 | OCRA | OCRA challenge-response |
| 4 | OCRAAndPIN | OCRA with PIN |
| 5 | OCRAHiSense | OCRA High Sensitivity |
| 6 | OCRAHiSenseAndPIN | OCRA High Sensitivity with PIN |
| 7 | Matrix | Matrix card |
| 8 | FIDOU2F | FIDO U2F |
| 9 | FIDOUAF | FIDO UAF |
| 10 | DynamicCvcEvent | Dynamic CVC (Event-based) |
| 11 | DynamicCvcTime | Dynamic CVC (Time-based) |
| 12 | DynamicCvcTimeAndPassword | Dynamic CVC with PIN |
| 14 | Event256 | HOTP SHA-256 |
| 15 | Time256 | TOTP SHA-256 |
| 16 | DynamicCvcEvent256 | Dynamic CVC Event SHA-256 |
| 17 | DynamicCvcTime256 | Dynamic CVC Time SHA-256 |
| 18 | Event512 | HOTP SHA-512 |
| 19 | Time512 | TOTP SHA-512 |
| 20 | DynamicCvcEvent512 | Dynamic CVC Event SHA-512 |
| 21 | DynamicCvcTime512 | Dynamic CVC Time SHA-512 |
| 22 | OffLine | Offline codes |
| 24 | FIDO2_UV | FIDO2 with User Verification (passwordless) |
| 25 | FIDO2_2FA | FIDO2 Second Factor |

### DeviceEnabledStatusEnum
| Value | Name | Description |
|-------|------|-------------|
| -2 | All | All statuses (filter only) |
| -1 | New | New/unactivated device |
| 0 | Enabled | Device is enabled |
| 1 | Disabled | Device is disabled |
| 2 | TestMode | Device in test mode |

### UserStatusEnum
| Value | Name | Description |
|-------|------|-------------|
| 0 | Enabled | User account is enabled |
| 1 | Disabled | User account is disabled |

### AdminRoleEnum
| Value | Name | Description |
|-------|------|-------------|
| 0 | SuperAdministrator | Super Administrator role |
| 1 | Administrator | Administrator role |
| 2 | UserManager | User Manager role |
| 3 | HelpDeskSupport | Help Desk Support role |
| 4 | HelpDeskManager / AAO | Help Desk Manager role |
| 20 | None | No administrative role (regular user) |
| 99 | All | All roles (filter only) |

### SendOtpDeliveryMethod
| Value | Name | Alias | Description |
|-------|------|-------|-------------|
| 0 | Sms | "sms", "s" | Send OTP via SMS |
| 1 | Email | "email", "e" | Send OTP via Email |
| 2 | Call | "call", "c" | Send OTP via Voice Call |

### SendPushMessageDeliveryMethod
| Value | Name | Alias | Description |
|-------|------|-------|-------------|
| 0 | PushSmsQuestion | "pushsmsquestion", "pq" | Push SMS question |
| 1 | PushAppFidoU2F | "pushappu2f", "pauf2" | Push App FIDO U2F |
| 2 | PushAppQuestion | "pushapp", "pa" | Push App question |
| 3 | PushOtp | - | Push OTP |
| 4 | PushVoice | "pushvoice", "pv" | Push Voice call |

### ApiPermissionsEnum
| Value | Name | Description |
|-------|------|-------------|
| 1 | ValidateOtp | Validate OTP codes |
| 3 | ValidateOtpPin | Validate OTP with PIN |
| 4 | CreateServerChallenge | Create server challenge |
| 5 | CreateSessionToken | Create session tokens |
| 6 | CheckSessionToken | Check session token validity |
| 7 | ExpireSessionToken | Expire session tokens |
| 8 | FidoU2FEnroll | FIDO U2F enrollment |
| 9 | FidoU2FSign | FIDO U2F signing |
| 10 | FidoU2FDelete | Delete FIDO U2F keys |
| 11 | ValidateUser | Validate user credentials |
| 12 | AddUser | Add new users |
| 13 | UpdateUser | Update user information |
| 14 | DeleteUser | Delete users |
| 15 | ChangeUserPassword | Change user passwords |
| 16 | FindUser | Find single user |
| 17 | FindUsers | Find multiple users |
| 20 | ProvisionTokenOta | Provision token OTA |
| 21 | ProvisionTokenQr | Provision token QR code |
| 24 | SendDeviceActivation | Send device activation |
| 25 | SendPasswordRecovery | Send password recovery |
| 26 | DeviceStatus | Enable/disable devices |
| 27 | DeleteDevice | Delete devices |
| 28 | DeviceAssignment | Assign/unassign devices |
| 29 | DeviceActivation | Activate devices |
| 30 | FindDevice | Find devices |
| 31 | AddU2FDevice | Add U2F devices |
| 32 | AddOathDevice | Add OATH devices |
| 33 | SendPushApp | Send push app notifications |
| 34 | SendPushVoice | Send push voice calls |
| 35 | SendPushU2FApp | Send push U2F app |
| 36 | SendPushOtp | Send push OTP |
| 37 | SendPushSms | Send push SMS |
| 38 | SendPushCancel | Cancel push messages |
| 39 | GetVerifyMethods | Get verification methods |
| 40 | SyncOtp | Synchronize OTP device |
| 41 | SendOtpSms | Send OTP via SMS |
| 42 | SendOtpEmail | Send OTP via Email |
| 43 | SendOtpVoice | Send OTP via Voice |
| 44 | DirectorySync | Directory synchronization |
| 45 | EventLogSync | Event log synchronization |
| 49 | Fido2Attestation | FIDO2 attestation |
| 50 | Fido2Assertion | FIDO2 assertion |
| 51 | Fido2List | FIDO2 list authenticators |
| 52 | Fido2Delete | FIDO2 delete authenticators |
| 53 | GetLicense | Get license information (auto-granted) |

---

## API Endpoints

### Authentication APIs

---

#### validate_oath_otp
Validates an OTP code for a user.

**Type:** `validate_oath_otp`  
**Permission Required:** `ValidateOtp` (1)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"validate_oath_otp"` |
| `username` | string | Yes | User's login name |
| `otp` or `code` | string | Yes | OTP code to validate |
| `psn` | string | No | Printed serial number of specific token |
| `ocodes` | short | No | Number of offline codes to return |

**Request Example:**
```json
{
    "type": "validate_oath_otp",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "code": "123456"
}
```

**Success Response:**
```json
{
    "type": "validate_oath_otp",
    "errorCode": 0,
    "errorMessage": "OK",
    "ocraServerCode": "",
    "offlineCodes": []
}
```

---

#### validate_otp_pin_mode
Validates an OTP with PIN in a specific mode.

**Type:** `validate_otp_pin_mode`  
**Permission Required:** `ValidateOtpPin` (3)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"validate_otp_pin_mode"` |
| `username` | string | Yes | User's login name |
| `otp` | string | Yes | OTP code |
| `pin` | string | Yes | PIN code |
| `psn` | string | No | Printed serial number |

---

#### validate_user
Validates user credentials and optionally creates a session token.

**Type:** `validate_user`  
**Permission Required:** `ValidateUser` (11)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"validate_user"` |
| `username` | string | Yes | User's login name |
| `pw` | string | No | User's password |
| `sessionIp` | string | No | Session IP address |
| `noAuth` | string | No | "1" to skip authentication |
| `sessionTokenDurationMinutes` | short | No | Session token duration (default: 30) |

**Request Example:**
```json
{
    "type": "validate_user",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "pw": "password123"
}
```

**Success Response (with auth):**
```json
{
    "type": "validate_user",
    "errorCode": 0,
    "errorMessage": "OK",
    "sessionToken": "abc123-session-token",
    "role": 20
}
```

**Success Response (noAuth=1):**
```json
{
    "type": "validate_user",
    "errorCode": 0,
    "errorMessage": "OK",
    "userStatus": 0,
    "role": 20,
    "devices": [
        {
            "psn": "TOKEN001",
            "deviceType": 9,
            "otpType": 1,
            "deviceStatus": 0,
            "tokenID": "unique-id"
        }
    ]
}
```

---

#### send_oath_otp
Sends an OTP to the user via SMS, Email, or Voice call.

**Type:** `send_oath_otp`  
**Permission Required:** `SendOtpSms` (41), `SendOtpEmail` (42), or `SendOtpVoice` (43)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"send_oath_otp"` |
| `username` | string | Yes | User's login name |
| `deliveryMethod` | string/int | No | `"sms"`, `"email"`, `"call"` or 0, 1, 2 (default: sms) |
| `alternateAddress` | string | No | Alternate phone/email address |

**Request Example:**
```json
{
    "type": "send_oath_otp",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "deliveryMethod": "email"
}
```

**Success Response:**
```json
{
    "type": "send_oath_otp",
    "errorCode": 0,
    "errorMessage": "OK"
}
```

---

#### create_server_challenge
Creates a server challenge for OCRA authentication.

**Type:** `create_server_challenge`  
**Permission Required:** `CreateServerChallenge` (4)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"create_server_challenge"` |
| `username` | string | Yes | User's login name |
| `psn` | string | No | Printed serial number |

---

### User Management APIs

---

#### add_user
Creates a new user account (without device).

**Type:** `add_user`  
**Permission Required:** `AddUser` (12)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"add_user"` |
| `username` | string | Yes | Login name (max 50 chars) |
| `firstName` | string | No | First name (max 50 chars) |
| `lastName` | string | No | Last name (max 50 chars) |
| `email` | string | No | Email address (max 100 chars) |
| `pw` | string | No | Password (max 175 chars) |
| `mobile` | string | No | Mobile phone (max 20 chars) |
| `userStatus` | string | No | `"ENABLED"`, `"DISABLED"`, `"0"`, `"1"` |
| `group` | string | No | Group name to add user to |
| `ssoIdentity` | string | No | SSO identity |
| `role` | string | No | AdminRoleEnum value (if allowed by config) |

**Request Example:**
```json
{
    "type": "add_user",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "mobile": "+1234567890",
    "userStatus": "ENABLED"
}
```

**Success Response:**
```json
{
    "type": "add_user",
    "errorCode": 0,
    "errorMessage": "OK",
    "deviceId": ""
}
```

---

#### add_oath_user
Creates a new user account with an OATH token.

**Type:** `add_oath_user`  
**Permission Required:** `AddUser` (12) + `AddOathDevice` (32)

**Request Parameters:**
All parameters from `add_user` plus:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deviceType` | int | Yes | DeviceTypesEnum value |
| `otpType` | int | Yes | OTPTypesEnum value |
| `otpLength` | int | No | OTP length (default: 6) |
| `windowSize` | int | No | OTP window size (default: 30) |
| `timeDrift` | int | No | Time drift (default: 5) |
| `psn` | string | No | Printed serial number |
| `secretKeyHex` | string | No | Secret key in hex format |
| `secretKeyHexBase64` | string | No | Secret key in base64 format |
| `otpPin` | string | No | OTP PIN |
| `counter` | string | No | HOTP counter |
| `startingCounter` | string | No | Starting counter |
| `expirationDate` | string | No | Token expiration date |
| `deviceStatus` | string | No | `"ENABLED"`, `"DISABLED"`, `"New"`, `"Test"` |
| `mobileUsage` | int | No | Mobile usage flags (legacy) |
| `mobileAuth` | int | No | 1 = require credentials |
| `mobileTokenIssuer` | string | No | Issuer for soft token |
| `softTokenAlias` | string | No | Token alias/name |
| `notificationMethod` | string | No | Notification transport method |

**Request Example:**
```json
{
    "type": "add_oath_user",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "deviceType": 9,
    "otpType": 1,
    "otpLength": 6,
    "windowSize": 30
}
```

**Success Response:**
```json
{
    "type": "add_oath_user",
    "errorCode": 0,
    "errorMessage": "OK",
    "deviceId": "generated-device-id"
}
```

---

#### add_oath_device
Adds an OATH token to an existing user.

**Type:** `add_oath_device`  
**Permission Required:** `AddOathDevice` (32)

**Request Parameters:**
Same device parameters as `add_oath_user`, requires `username`.

---

#### add_u2f_user
Creates a new user with a FIDO U2F device.

**Type:** `add_u2f_user`  
**Permission Required:** `AddUser` (12) + `AddOathDevice` (32)

---

#### add_u2f_device
Adds a FIDO U2F device to an existing user.

**Type:** `add_u2f_device`  
**Permission Required:** `AddOathDevice` (32)

---

#### update_user
Updates an existing user's information.

**Type:** `update_user`  
**Permission Required:** `UpdateUser` (13)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"update_user"` |
| `username` | string | Yes | Login name of user to update |
| `firstName` | string | No | New first name |
| `lastName` | string | No | New last name |
| `email` | string | No | New email address |
| `pw` | string | No | New password |
| `mobile` | string | No | New mobile phone |
| `userStatus` | string | No | `"ENABLED"` or `"DISABLED"` |
| `ssoIdentity` | string | No | SSO identity |

**Request Example:**
```json
{
    "type": "update_user",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "email": "john.doe.new@example.com",
    "userStatus": "ENABLED"
}
```

**Success Response:**
```json
{
    "type": "update_user",
    "errorCode": 0,
    "errorMessage": "OK"
}
```

---

#### delete_user
Deletes a user account.

**Type:** `delete_user`  
**Permission Required:** `DeleteUser` (14)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"delete_user"` |
| `username` | string | Yes | Login name of user to delete |

---

#### find_user
Retrieves user information and associated devices.

**Type:** `find_user`  
**Permission Required:** `FindUser` (16)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"find_user"` |
| `username` | string | Yes | Login name to search |
| `checkEmail` | bool | No | Also search by email address |

**Request Example:**
```json
{
    "type": "find_user",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe"
}
```

**Success Response:**
```json
{
    "type": "find_user",
    "errorCode": 0,
    "errorMessage": "OK",
    "userStatus": 0,
    "username": "john.doe",
    "pw": "",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "email": "john.doe@example.com",
    "bypassMFA": "0",
    "vip": false,
    "role": "None",
    "Devices": [
        {
            "type": "find_device",
            "errorCode": 0,
            "errorMessage": "OK",
            "deviceType": 9,
            "otpType": 1,
            "otpLength": 6,
            "assigned": 1,
            "deviceStatus": 0,
            "assignedToID": 123,
            "username": "john.doe",
            "email": "john.doe@example.com",
            "tokenID": "unique-token-id",
            "psn": "TOKEN001",
            "tokenAlias": "My Phone",
            "activationStatus": 1
        }
    ]
}
```

---

#### find_users
Retrieves a list of users matching criteria.

**Type:** `find_users`  
**Permission Required:** `FindUsers` (17)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"find_users"` |
| `filter` | string | No | Search filter |

---

#### change_user_password
Changes a user's password.

**Type:** `change_user_password`  
**Permission Required:** `ChangeUserPassword` (15)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"change_user_password"` |
| `username` | string | Yes | User's login name |
| `currentPassword` | string | Yes | Current password |
| `newPassword` | string | Yes | New password |

---

#### send_password_recovery
Sends a password recovery email to the user.

**Type:** `send_password_recovery`  
**Permission Required:** `SendPasswordRecovery` (25)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"send_password_recovery"` |
| `username` | string | Yes | User's login name |

---

#### password_recovery_change_password
Changes password using recovery token.

**Type:** `password_recovery_change_password`  
**Permission Required:** `SendPasswordRecovery` (25)

---

### Token/Device Management APIs

---

#### find_device
Retrieves device information.

**Type:** `find_device`  
**Permission Required:** `FindDevice` (30)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"find_device"` |
| `psn` | string | No* | Printed serial number |
| `tokenID` | string | No* | Unique token identifier |

*One of `psn` or `tokenID` is required.

**Request Example:**
```json
{
    "type": "find_device",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "psn": "TOKEN001"
}
```

**Success Response:**
```json
{
    "type": "find_device",
    "errorCode": 0,
    "errorMessage": "OK",
    "deviceType": 9,
    "otpType": 1,
    "otpLength": 6,
    "assigned": 1,
    "deviceStatus": 0,
    "assignedToID": 123,
    "username": "john.doe",
    "email": "john.doe@example.com",
    "tokenID": "unique-token-id",
    "psn": "TOKEN001",
    "tokenAlias": "My Phone",
    "activationStatus": 1
}
```

---

#### assign_device
Assigns a token to a user.

**Type:** `assign_device`  
**Permission Required:** `DeviceAssignment` (28)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"assign_device"` |
| `username` | string | Yes | User to assign to |
| `psn` | string | Yes | Printed serial number |
| `force` | string | No | `"TRUE"` to allow reassignment |

**Request Example:**
```json
{
    "type": "assign_device",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "psn": "TOKEN001",
    "force": "TRUE"
}
```

---

#### unassign_device
Unassigns a token from a user.

**Type:** `unassign_device`  
**Permission Required:** `DeviceAssignment` (28)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"unassign_device"` |
| `username` | string | Yes | User to unassign from |
| `psn` | string | Yes | Printed serial number |

---

#### enable_device
Enables a token.

**Type:** `enable_device`  
**Permission Required:** `DeviceStatus` (26)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"enable_device"` |
| `username` | string | Yes | User's login name |
| `psn` | string | Yes | Printed serial number |

---

#### disable_device
Disables a token.

**Type:** `disable_device`  
**Permission Required:** `DeviceStatus` (26)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"disable_device"` |
| `username` | string | Yes | User's login name |
| `psn` | string | Yes | Printed serial number |

---

#### delete_device
Deletes a token.

**Type:** `delete_device`  
**Permission Required:** `DeleteDevice` (27)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"delete_device"` |
| `username` | string | Yes | User's login name |
| `psn` | string | Yes | Printed serial number |

---

#### active_oath_device
Activates an OATH device using two consecutive OTPs.

**Type:** `active_oath_device`  
**Permission Required:** `DeviceActivation` (29)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"active_oath_device"` |
| `username` | string | Yes | User's login name |
| `otp1` | string | Yes | First OTP |
| `otp2` | string | Yes | Second OTP |
| `psn` | string | No | Printed serial number |

---

#### sync_oath_device
Synchronizes an OATH device using two consecutive OTPs.

**Type:** `sync_oath_device`  
**Permission Required:** `SyncOtp` (40)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"sync_oath_device"` |
| `username` | string | Yes | User's login name |
| `otp1` | string | Yes | First OTP |
| `otp2` | string | Yes | Second OTP |
| `psn` | string | No | Printed serial number |

---

#### provision_device / provision_oath_device
Provisions a mobile token (used by mobile app).

**Type:** `provision_device` or `provision_oath_device`  
**Permission Required:** `ProvisionTokenOta` (20) (optional - can be called without auth if direct provisioning enabled)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"provision_device"` or `"provision_oath_device"` |
| `username` | string | Yes | User's login name |
| `code` | string | Yes | Activation code |

---

#### get_oath_device_qrcode
Gets a QR code for provisioning a soft token.

**Type:** `get_oath_device_qrcode`  
**Permission Required:** `ProvisionTokenQr` (21)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"get_oath_device_qrcode"` |
| `username` | string | Yes | User's login name |
| `psn` | string | No | Printed serial number |

**Success Response:**
```json
{
    "type": "get_oath_device_qrcode",
    "errorCode": 0,
    "errorMessage": "OK",
    "qrCode": "otpauth://totp/...",
    "base64QRCode": "base64-encoded-image"
}
```

---

#### send_device_activation
Sends device activation notification to user.

**Type:** `send_device_activation`  
**Permission Required:** `SendDeviceActivation` (24)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"send_device_activation"` |
| `username` | string | Yes | User's login name |
| `psn` | string | No | Printed serial number |
| `deliveryMethod` | string | No | Delivery method |

---

### Push Authentication APIs

---

#### send_push_message
Sends a push authentication request.

**Type:** `send_push_message`  
**Permission Required:** `SendPushApp` (33), `SendPushVoice` (34), `SendPushU2FApp` (35), or `SendPushSms` (37)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"send_push_message"` |
| `username` | string | Yes | User's login name |
| `appName` | string | Yes | Application name for display |
| `deliveryMethod` | string/int | No | See SendPushMessageDeliveryMethod enum |
| `printedSerialNumber` | string | No | Specific token PSN |
| `authnAccount` | string | No | Account name (default: "account") |
| `authnReason` | string | No | Reason for auth (default: "Login") |
| `relyingPartyUrl` | string | No | Relying party URL |
| `voiceCallSendMessage` | string | No | Voice call message |
| `alternateAddress` | string | No | Alternate phone/address |

**Request Example:**
```json
{
    "type": "send_push_message",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "appName": "Corporate VPN",
    "deliveryMethod": "pushapp",
    "authnReason": "VPN Login"
}
```

**Success Response:**
```json
{
    "type": "send_push_message",
    "errorCode": 0,
    "errorMessage": "OK",
    "pushToken": "push-request-token-id"
}
```

---

#### is_user_push_authenticated
Checks if user has responded to push authentication.

**Type:** `is_user_push_authenticated`  
**Permission Required:** `ValidateOtp` (1)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"is_user_push_authenticated"` |
| `username` | string | Yes | User's login name |
| `pushToken` | string | Yes | Push token from send_push_message |

**Success Response (authenticated):**
```json
{
    "type": "is_user_push_authenticated",
    "errorCode": 0,
    "errorMessage": "OK"
}
```

---

#### cancel_push_message
Cancels a pending push authentication request.

**Type:** `cancel_push_message`  
**Permission Required:** `SendPushCancel` (38)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"cancel_push_message"` |
| `username` | string | Yes | User's login name |
| `pushToken` | string | Yes | Push token to cancel |

---

#### receive_push_response
Receives push response from mobile app.

**Type:** `receive_push_response`  
**Permission Required:** Push permissions (mobile only)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"receive_push_response"` |
| `response` | string | Yes | `"yes"` or `"no"` |
| `authnUserReqId` | string | Yes | Authentication request ID |

---

#### tap_auth_response
Alternative push response endpoint (from mobile app).

**Type:** `tap_auth_response`  
**Permission Required:** Push permissions (mobile only)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"tap_auth_response"` |
| `errorCode` | int | Yes | 0 = accepted, other = rejected |
| `token` | string | No | Device token |
| `appReqId` | string | Yes | Application request ID |

---

#### provision_push_device
Provisions a push-enabled mobile device.

**Type:** `provision_push_device`  
**Permission Required:** Optional (if direct provisioning enabled)

---

#### update_push_user_device
Updates push device registration.

**Type:** `update_push_user_device`  
**Permission Required:** Push permissions

---

#### delete_push_user_device
Removes push device registration.

**Type:** `delete_push_user_device`  
**Permission Required:** `DeletePushAccount` (19)

---

### Session Management APIs

---

#### create_session_token
Creates a session token for a user.

**Type:** `create_session_token`  
**Permission Required:** `CreateSessionToken` (5)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"create_session_token"` |
| `username` | string | Yes | User's login name |
| `pw` | string | No | User's password |
| `sessionTokenDurationMinutes` | short | No | Token duration (default: 30) |
| `sessionTokenType` | int | No | Token type |

**Request Example:**
```json
{
    "type": "create_session_token",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe",
    "sessionTokenDurationMinutes": 60
}
```

**Success Response:**
```json
{
    "type": "create_session_token",
    "errorCode": 0,
    "errorMessage": "OK",
    "sessionToken": "generated-session-token"
}
```

---

#### is_session_token_valid
Checks if a session token is valid.

**Type:** `is_session_token_valid`  
**Permission Required:** `CheckSessionToken` (6)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"is_session_token_valid"` |
| `username` | string | No | User's login name |
| `sessionToken` | string | Yes | Session token to validate |
| `sessionIp` | string | No | Session IP to validate |

**Request Example:**
```json
{
    "type": "is_session_token_valid",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "sessionToken": "session-token-to-check"
}
```

---

#### expire_session_token
Expires/invalidates a session token.

**Type:** `expire_session_token`  
**Permission Required:** `ExpireSessionToken` (7)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"expire_session_token"` |
| `username` | string | Yes | User's login name |
| `sessionToken` | string | Yes | Session token to expire |

---

#### find_account_by_mobile_session_token
Finds account associated with a mobile session token.

**Type:** `find_account_by_mobile_session_token`  
**Permission Required:** Session permissions

---

### FIDO U2F APIs

---

#### pre_enroll
Initiates FIDO U2F enrollment.

**Type:** `pre_enroll`  
**Permission Required:** `FidoU2FEnroll` (8)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"pre_enroll"` |
| `username` | string | Yes | User's login name |
| `appId` | string | Yes | Application ID (facet) |

**Success Response:**
```json
{
    "type": "u2f_register_request",
    "errorCode": 0,
    "errorMessage": "OK",
    "registerRequests": [...],
    "registeredKeys": [...],
    "sessionId": "enrollment-session-id"
}
```

---

#### enroll
Completes FIDO U2F enrollment.

**Type:** `enroll`  
**Permission Required:** `FidoU2FEnroll` (8)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"enroll"` |
| `username` | string | Yes | User's login name |
| `registrationData` | string | Yes | Base64 registration data |
| `clientData` | string | Yes | Base64 client data |
| `sessionId` | string | Yes | Session ID from pre_enroll |
| `psn` | string | No | Printed serial number |
| `securityKeyName` | string | No | Name for security key |
| `code` | string | No | Activation code |

---

#### pre_sign
Initiates FIDO U2F authentication.

**Type:** `pre_sign`  
**Permission Required:** `FidoU2FSign` (9)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"pre_sign"` |
| `username` | string | Yes | User's login name |
| `appId` | string | Yes | Application ID (facet) |

**Success Response:**
```json
{
    "type": "u2f_sign_request",
    "errorCode": 0,
    "errorMessage": "OK",
    "challenge": "...",
    "registeredKeys": [...],
    "sessionId": "sign-session-id"
}
```

---

#### sign
Completes FIDO U2F authentication.

**Type:** `sign`  
**Permission Required:** `FidoU2FSign` (9)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"sign"` |
| `username` | string | Yes | User's login name |
| `signatureData` | string | Yes | Base64 signature data |
| `clientData` | string | Yes | Base64 client data |
| `keyHandle` | string | Yes | Key handle |
| `sessionId` | string | Yes | Session ID from pre_sign |

---

#### delete_key
Deletes a specific FIDO U2F key.

**Type:** `delete_key`  
**Permission Required:** `FidoU2FDelete` (10)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"delete_key"` |
| `username` | string | Yes | User's login name |
| `appId` | string | Yes | Application ID |
| `keyHandle` | string | Yes | Key handle to delete |

---

#### delete_all_keys
Deletes all FIDO U2F keys for a user/app.

**Type:** `delete_all_keys`  
**Permission Required:** `FidoU2FDelete` (10)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"delete_all_keys"` |
| `username` | string | Yes | User's login name |
| `appId` | string | Yes | Application ID |

---

#### delete_stale_keys
Deletes stale/expired FIDO keys.

**Type:** `delete_stale_keys`  
**Permission Required:** `FidoU2FDelete` (10)

---

#### update_fido_device_name
Updates the friendly name of a FIDO device.

**Type:** `update_fido_device_name`  
**Permission Required:** FIDO permissions

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"update_fido_device_name"` |
| `username` | string | Yes | User's login name |
| `keyHandle` | string | Yes | Key handle |
| `deviceName` | string | Yes | New device name |

---

### System APIs

---

#### get_system_time
Returns the server's current Unix timestamp.

**Type:** `get_system_time`  
**Permission Required:** None (no authentication required)

**Request Example:**
```json
{
    "type": "get_system_time"
}
```

**Success Response:**
```json
{
    "type": "get_system_time",
    "errorCode": 0,
    "errorMessage": "OK",
    "serverTime": 1704067200
}
```

---

#### get_license
Returns license information.

**Type:** `get_license`  
**Permission Required:** `GetLicense` (53) - automatically granted to any valid API key

**Request Example:**
```json
{
    "type": "get_license",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret"
}
```

**Success Response (V2 License):**
```json
{
    "type": "get_license",
    "errorCode": 0,
    "errorMessage": "OK",
    "licenseVersion": 2,
    "licenseStatus": "Valid",
    "expirationDate": "2025-12-31T00:00:00.0000000",
    "hasExpirationDate": true,
    "maxUsers": 1000,
    "hostedInstall": false,
    "communityEdition": false,
    "evaluation": false,
    "evaluationExpired": false,
    "daysUsed": 0,
    "maxDays": 0,
    "product": {
        "name": "SurePassID Authentication Services",
        "edition": "Enterprise",
        "version": "2025.4",
        "maxTokens": 5000,
        "maxUsers": 1000,
        "multiTenantInstall": false,
        "componentList": ["Mfa Server", "Radius", "Saml2 IdP"],
        "platformList": ["On-Premises"]
    },
    "company": {
        "name": "Acme Corporation",
        "contact": "John Doe",
        "email": "john.doe@acme.com"
    },
    "licensing": {
        "issueDate": "2025-01-01T00:00:00.0000000",
        "licenseKey": "SPID-2025-ENT-001",
        "bypassHostNameValidation": false
    }
}
```

---

#### get_verified_methods
Returns available verification methods for a user.

**Type:** `get_verified_methods`  
**Permission Required:** `GetVerifyMethods` (39)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"get_verified_methods"` |
| `username` | string | Yes | User's login name |

---

#### trace
Writes a trace log entry (debugging).

**Type:** `trace`  
**Permission Required:** Debug permissions

---

### Sync APIs

---

#### directory_sync_start
Starts a directory synchronization job.

**Type:** `directory_sync_start`  
**Permission Required:** `DirectorySync` (44)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"directory_sync_start"` |

---

#### event_log_sync_start
Starts an event log synchronization job.

**Type:** `event_log_sync_start`  
**Permission Required:** `EventLogSync` (45)

**Request Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `"event_log_sync_start"` |
| `lastSyncTime` | long | No | Unix timestamp of last sync |

**Success Response:**
```json
{
    "type": "event_log_sync_start",
    "errorCode": 0,
    "errorMessage": "OK",
    "events": [...],
    "lastSyncTime": 1704067200,
    "hasMore": false
}
```

---

## Error Codes Reference

### Common Error Codes

| Code | Name | Description |
|------|------|-------------|
| 0 | Success | Operation completed successfully |
| 403 | Forbidden | API access violation / invalid credentials |
| 9001 | PartnerNotFound | Partner/organization not found |
| 9002 | PartnerUserNotFound | User not found |
| 9003 | DeviceNotFound | Token/device not found |
| 9004 | InvalidOtp | Invalid OTP code |
| 9005 | DeviceDisabled | Token is disabled |
| 9006 | UserDisabled | User account is disabled |
| 9007 | DeviceExpired | Token has expired |
| 9008 | MaxOtpAttempts | Maximum OTP attempts exceeded |
| 9009 | DeviceLocked | Token is locked |
| 9010 | InvalidPin | Invalid PIN |
| 9011 | PasswordExpired | Password has expired |
| 9012 | PasswordInvalid | Invalid password |
| 9013 | SessionExpired | Session has expired |
| 9014 | SessionInvalid | Invalid session |
| 9101 | DiagnosticTrace | General diagnostic error |
| 9131 | ApiAccessViolation | API permission denied |
| 9132 | PartnerLoginFailed | Partner login failed |

---

## API Permissions Reference

### Permission Matrix by API Type

| API Type | Permission Required | Permission ID |
|----------|---------------------|---------------|
| `validate_oath_otp` | ValidateOtp | 1 |
| `validate_otp_pin_mode` | ValidateOtpPin | 3 |
| `create_server_challenge` | CreateServerChallenge | 4 |
| `create_session_token` | CreateSessionToken | 5 |
| `is_session_token_valid` | CheckSessionToken | 6 |
| `expire_session_token` | ExpireSessionToken | 7 |
| `pre_enroll`, `enroll` | FidoU2FEnroll | 8 |
| `pre_sign`, `sign` | FidoU2FSign | 9 |
| `delete_key`, `delete_all_keys` | FidoU2FDelete | 10 |
| `validate_user` | ValidateUser | 11 |
| `add_user`, `add_oath_user`, `add_u2f_user` | AddUser | 12 |
| `update_user` | UpdateUser | 13 |
| `delete_user` | DeleteUser | 14 |
| `change_user_password` | ChangeUserPassword | 15 |
| `find_user` | FindUser | 16 |
| `find_users` | FindUsers | 17 |
| `send_device_activation` | SendDeviceActivation | 24 |
| `send_password_recovery` | SendPasswordRecovery | 25 |
| `enable_device`, `disable_device` | DeviceStatus | 26 |
| `delete_device` | DeleteDevice | 27 |
| `assign_device`, `unassign_device` | DeviceAssignment | 28 |
| `active_oath_device` | DeviceActivation | 29 |
| `find_device` | FindDevice | 30 |
| `add_u2f_device` | AddU2FDevice | 31 |
| `add_oath_device` | AddOathDevice | 32 |
| `send_push_message` (app) | SendPushApp | 33 |
| `send_push_message` (voice) | SendPushVoice | 34 |
| `send_push_message` (u2f) | SendPushU2FApp | 35 |
| `send_push_message` (sms) | SendPushSms | 37 |
| `cancel_push_message` | SendPushCancel | 38 |
| `get_verified_methods` | GetVerifyMethods | 39 |
| `sync_oath_device` | SyncOtp | 40 |
| `send_oath_otp` (sms) | SendOtpSms | 41 |
| `send_oath_otp` (email) | SendOtpEmail | 42 |
| `send_oath_otp` (voice) | SendOtpVoice | 43 |
| `directory_sync_start` | DirectorySync | 44 |
| `event_log_sync_start` | EventLogSync | 45 |
| `get_license` | GetLicense | 53 |

---

## Complete API Type Reference

| API Type String | Constant Name |
|-----------------|---------------|
| `get_verified_methods` | GET_VERIFIED_METHODS |
| `password_recovery_change_password` | PASSWORD_RECOVERY_CHANGE_PASSWORD |
| `change_user_password` | CHANGE_USER_PASSWORD |
| `get_system_time` | GET_SYSTEM_TIME |
| `get_license` | GET_LICENSE |
| `send_password_recovery` | SEND_PASSWORD_RECOVERY |
| `create_session_token` | CREATE_SESSION_TOKEN |
| `send_device_activation` | SEND_DEVICE_ACTIVATION |
| `expire_session_token` | DELETE_SESSION_TOKEN |
| `find_account_by_mobile_session_token` | FIND_ACCOUNT_BY_MOBILE_SESSION_TOKEN |
| `find_device` | FIND_DEVICE |
| `find_user` | FIND_USER |
| `find_users` | FIND_USERS |
| `assign_device` | ASSIGN_DEVICE |
| `enable_device` | ENABLE_DEVICE |
| `disable_device` | DISABLE_DEVICE |
| `delete_device` | DELETE_DEVICE |
| `unassign_device` | UNASSIGN_DEVICE |
| `is_user_push_authenticated` | IS_USER_PUSH_AUTHENTICATED |
| `is_session_token_valid` | IS_SESSION_TOKEN_VALID |
| `add_u2f_user` | ADD_U2F_USER_ACCOUNT |
| `validate_u2f_user` | VERIFY_U2F_USER_ACCOUNT |
| `validate_user` | VERIFY_USER_ACCOUNT |
| `add_u2f_device` | ADD_U2F_USER_DEVICE |
| `add_oath_user` | ADD_OATH_USER_ACCOUNT |
| `update_user` | UPDATE_USER |
| `add_user` | ADD_USER |
| `delete_user` | DELETE_USER |
| `get_oath_device_qrcode` | GET_OATH_USER_DEVICE_QRCODE |
| `provision_oath_device` | PROVISION_OATH_DEVICE |
| `provision_device` | PROVISION_DEVICE |
| `add_oath_device` | ADD_OATH_DEVICE |
| `delete_key` | DELETE_SECRET_KEY |
| `delete_all_keys` | DELETE_ALL_SECRET_KEYS |
| `validate_oath_otp` | VALIDATE_OTP |
| `send_oath_otp` | SEND_OTP |
| `send_push_message` | SEND_PUSH_MESSAGE |
| `receive_push_response` | RECEIVE_PUSH_RESPONSE |
| `tap_auth_response` | TAP_AUTH_RESPONSE |
| `provision_push_device` | PROVISION_PUSH_DEVICE |
| `add_push_user_device` | ADD_PUSH_USER_DEVICE |
| `update_push_user_device` | UPDATE_PUSH_USER_DEVICE |
| `delete_push_user_device` | DELETE_PUSH_USER_DEVICE |
| `active_oath_device` | ACTIVATE_OTP_DEVICE |
| `sync_oath_device` | SYNC_OTP_DEVICE |
| `create_server_challenge` | CREATE_SERVER_CHALLENGE |
| `validate_otp_pin_mode` | VALIDATE_OTP_PIN_MODE |
| `cancel_push_message` | CANCEL_PUSH_MESSAGE |
| `update_fido_device_name` | UPDATE_FIDO_DEVICE_NAME |
| `delete_stale_keys` | DELETE_STALE_KEYS |
| `pre_enroll` | PRE_ENROLL |
| `enroll` | ENROLL |
| `pre_sign` | PRE_SIGN |
| `sign` | SIGN |
| `event_log_sync_start` | EVENT_LOG_SYNC_START |
| `directory_sync_start` | DIRECTORY_SYNC_START |
| `trace` | WRITE_TRACE |

---

*Document generated for SurePassID Authentication Services Release 2025.4*  
*For verification testing of rewritten implementations*
