SurePassID REST API V1

SurePassID Authentication Server

Document Purpose: Complete API specification for verification testing of rewritten implementations
Coverage: Core MFA APIs plus PIV Smart Card (enrollment, authentication, header-auth, device management, admin batch enrollment, chip-personalization audit, PUK escrow, PIN-reset and first-PIN activation voucher flows, identity proofing, IoT authorization) and Token Order/Inventory APIs.

Overview

The SurePassID REST API provides programmatic access to multi-factor authentication services. All API requests use JSON format and are processed through the https://<server>/api/mfa/v1 endpoint.

Base URL

https://<server>/api/mfa/v1

Content Type

Content-Type: application/json

Authentication

Most API endpoints require authentication using an API Key pair: the API Key ID and the API Key (secret). The client library supports two mutually exclusive ways of transmitting these credentials, controlled by the internal _useHttpHeader flag:

HTTP Basic authentication (header mode) - RECOMMENDED. When header mode is enabled, the credentials are not placed in the request body. Instead the client builds a standard HTTP Authorization: Basic header where the value is the Base64 encoding of ApiKeyId:ApiKey - the API Key ID as the Basic-auth username and the API Key as the Basic-auth password. The body fields spAccountLoginName / spAccountLoginKey are sent as null in this mode.
Request-body authentication - DEPRECATED. When header mode is disabled, the credentials are carried in the JSON body via spAccountLoginName (the API Key ID) and spAccountLoginKey (the API Key), and no Authorization header is sent. This mode is retained for backward compatibility only and should not be used for new integrations; prefer HTTP Basic authentication (header mode) instead.
Fido2 - The MFA server supports FIdo2 via proxy (transparent) or application gateway as configured in the MFA server web.config to Fido2 API server using standard Fido2 endpoints as documented in Fido2 standards.

HTTP Basic Authentication Header (recommended)

When header mode is active, the client emits:

Authorization: Basic <base64(ApiKeyId:ApiKey)>

Where the token is computed as Convert.ToBase64String(Encoding.ASCII.GetBytes($"{ApiKeyId}:{ApiKey}")) - i.e. the API Key ID is the Basic-auth username and the API Key is the Basic-auth password. The library sets this header in SetBasicHttpAuthorizationHeader (AuthServerRestApi.HttpClient*.cs).

Example (header mode):

POST /api/ServerProxy.ashx HTTP/1.1
Content-Type: application/json
Authorization: Basic YXBpLWtleS1pZC1oZXJlOmFwaS1rZXktc2VjcmV0LWhlcmU=

{
    "type": "find_user",
    "username": "john.doe"
}

Authentication Fields (request-body mode - DEPRECATED)

DEPRECATED: Request-body authentication is retained for backward compatibility only. Use HTTP Basic authentication (header mode) for all new integrations.

Field	Type	Required	Description
`spAccountLoginName`	string	Yes*	API Key ID (Basic-auth username in header mode)
`spAccountLoginKey`	string	Yes*	API Key (Basic-auth password in header mode)

*Required for all endpoints except: get_system_time, provision_oath_device, provision_device, provision_push_device (when direct provisioning is enabled). In header mode these fields are omitted from the body and supplied via the Authorization: Basic header instead.

Example Authentication (request-body mode - DEPRECATED)

{
    "type": "find_user",
    "spAccountLoginName": "api-key-id-here",
    "spAccountLoginKey": "api-key-secret-here",
    "username": "john.doe"
}

Common Request/Response Structure

Standard Request Format

{
    "type": "<api_type>",
    "spAccountLoginName": "<api_key_id>",
    "spAccountLoginKey": "<api_key_secret>",
    // Additional parameters specific to the API
}

Standard Response Format

Success Response

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

Error Response

{
    "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)
54	PivEnroll	PIV certificate enrollment (`piv_pre_enroll`, `piv_enroll`)
55	PivAuth	PIV authentication (`piv_pre_auth`, `piv_auth`, `piv_header_auth`)
61	PivAdminEnroll	PIV admin batch enrollment (`piv_admin_enroll`)

Note: PIV device management, audit, PUK escrow, voucher flows, IoT authorization, and the Token Inventory APIs are gated by their own dedicated permissions (e.g. PivFindDevice, PivLogPerso, PivPinReset, PivActivation, TokenOrderFind, TokenInventoryAssign). See the Permission Matrix by API Type for the per-endpoint mapping.

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:

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

Success Response:

{
    "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:

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

Success Response (with auth):

{
    "type": "validate_user",
    "errorCode": 0,
    "errorMessage": "OK",
    "sessionToken": "abc123-session-token",
    "role": 20
}

Success Response (noAuth=1):

{
    "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:

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

Success Response:

{
    "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:

{
    "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:

{
    "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:

{
    "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:

{
    "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:

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

Success Response:

{
    "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:

{
    "type": "find_user",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "username": "john.doe"
}

Success Response:

{
    "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:

{
    "type": "find_device",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret",
    "psn": "TOKEN001"
}

Success Response:

{
    "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:

{
    "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:

{
    "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:

{
    "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:

{
    "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):

{
    "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:

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

Success Response:

{
    "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:

{
    "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:

{
    "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:

{
    "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:

{
    "type": "get_system_time"
}

Success Response:

{
    "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:

{
    "type": "get_license",
    "spAccountLoginName": "api-key-id",
    "spAccountLoginKey": "api-key-secret"
}

Success Response (V2 License):

{
    "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:

{
    "type": "event_log_sync_start",
    "errorCode": 0,
    "errorMessage": "OK",
    "events": [...],
    "lastSyncTime": 1704067200,
    "hasMore": false
}

PIV Smart Card APIs

These APIs support PIV/CAC smart card enrollment, authentication, device management, chip-personalization auditing, PUK escrow, PIN-reset and first-PIN activation voucher flows, IoT authorization, and admin batch enrollment. They are implemented by the AuthServerRestApi.PivSmartCard partial class.

piv_pre_enroll

Initiates PIV certificate enrollment (Step 1 of 2). Returns a challenge the client signs with the PIV private key.

Type: piv_pre_enroll
Permission Required: PivEnroll (54)

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_pre_enroll"`
`username`	string	Yes	User to enroll

Success Response:

{
    "type": "piv_pre_enroll",
    "errorCode": 0,
    "errorMessage": "OK",
    "sessionId": "guid",
    "challenge": "base64-nonce",
    "supportedAlgorithms": ["RS256", "ES256"]
}

Common errors: 9207 (PIV not enabled), 9133 (user not found), 9010 (database error).

piv_enroll

Completes PIV certificate enrollment (Step 2 of 2). Submits the DER certificate and challenge signature.

Type: piv_enroll
Permission Required: PivEnroll (54)

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_enroll"`
`username`	string	Yes	User being enrolled
`sessionId`	string	Yes	Session ID from `piv_pre_enroll`
`certificate`	string	Yes	Base64 DER certificate
`signedChallenge`	string	Yes	Base64 signature of the challenge
`deviceName`	string	No	Display name for the PIV device

Success Response:

{
    "type": "piv_enroll",
    "errorCode": 0,
    "errorMessage": "OK",
    "deviceId": "id",
    "psn": "PIV-A1B2C3D4",
    "subjectDN": "CN=...",
    "expirationDate": "2027-01-01",
    "keySlot": "9A"
}

Common errors: 9205, 9200, 9201, 9203, 9204, 9207, 9209, 9210.

piv_pre_auth

Initiates PIV authentication (Step 1 of 2). Returns a challenge and the user's registered certificates.

Type: piv_pre_auth
Permission Required: PivAuth (55)

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_pre_auth"`
`username`	string	Yes	User to authenticate

Common errors: 9207 (PIV not enabled), 9133 (user not found), 9206 (no certificates enrolled).

piv_auth

Completes PIV authentication (Step 2 of 2). Submits the challenge signature.

Type: piv_auth
Permission Required: PivAuth (55)

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_auth"`
`username`	string	Yes	User to authenticate
`sessionId`	string	Yes	Session ID from `piv_pre_auth`
`signedChallenge`	string	Yes	Base64 signature of the challenge
`certificateHash`	string	No	SHA-256 hex fingerprint of the certificate to use

Success Response:

{
    "type": "piv_auth",
    "errorCode": 0,
    "errorMessage": "OK",
    "sessionToken": "token",
    "certificateSubject": "CN=...",
    "keySlot": "9A"
}

Common errors: 9205, 9206, 9201, 9202, 9204.

piv_header_auth

Header-based PIV authentication for reverse-proxy (NGINX / IIS ARR) environments that terminate mTLS and forward the client certificate as HTTP headers.

Type: piv_header_auth
Permission Required: PivAuth (55)

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_header_auth"`
`certificateHash`	string	No	Fallback SHA-256 fingerprint (requires `Piv.HeaderAuth.AllowFingerprintOnly`)
`username`	string	No	Optional username constraint
`sessionTokenDurationMinutes`	int	No	Override default token lifetime

Forwarded Headers (proxy-emulated):

Header	Proxy Mode	Description
`X-Client-Cert`	NGINX	URL-encoded PEM certificate
`X-ARR-ClientCert`	IIS ARR	Raw base64 DER certificate
`X-Client-Cert-Verify`	Both	`SUCCESS` when `Piv.HeaderAuth.RequireProxyVerify` is enabled

Common errors: 9131, 9106, 9107, 9200, 9201, 9203, 9206, 9207.

piv_find_device

Looks up a PIV device by certificate hash or printed serial number.

Type: piv_find_device
Permission Required: PivFindDevice

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_find_device"`
`certificateHash`	string	No*	SHA-256 fingerprint (takes priority over `psn`)
`psn`	string	No*	Printed serial number

*At least one of certificateHash or psn is required. Common errors: 9207, 9021.

piv_delete_device

Deletes a PIV device and its certificate record.

Type: piv_delete_device
Permission Required: PivDeleteDevice

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_delete_device"`
`certificateHash`	string	No*	SHA-256 fingerprint (takes priority over `psn`)
`psn`	string	No*	Printed serial number

*At least one of certificateHash or psn is required. Common errors: 9207, 9021, 9010.

piv_admin_enroll

Enrolls one or more PIV certificates for a user without challenge-response proof (admin batch provisioning, e.g. YubiKey bulk issuance).

Type: piv_admin_enroll
Permission Required: PivAdminEnroll (61)

Request Parameters (single-slot):

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_admin_enroll"`
`username`	string	Yes	User to enroll against
`certificate`	string	Yes	Base64 DER certificate
`deviceName`	string	No	Display name (defaults to `PIV Card (<slot-hex>)`)
`keySlot`	int	No	154 (0x9A, default), 156 (0x9C), 157 (0x9D), 158 (0x9E)
`deviceStatus`	int	No	0 = Enabled (default), 1 = Disabled
`comments`	string	No	Free-text audit notes
`cardSerialNumber`	string	No	Physical serial for hollow-stub reconciliation (`{serial}-PIV`)

Request Parameters (multi-slot): Same as above but replace certificate/keySlot/deviceName/comments with a slots[] array (one entry per slot). Enrollment is all-or-nothing.

Common errors: 9207, 9200, 9201, 9210, 9133, 9129.

piv_log_perso

Reports a chip personalization outcome (audit only). No PIN, PUK, or key material is transmitted.

Type: piv_log_perso
Permission Required: PivLogPerso

Request Parameters (key fields):

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_log_perso"`
`cardSerial`	string	Yes*	Card serial
`personalizerId`	string	Yes*	Personalizer identity
`slot9AStatus`..`slot9EStatus`	string	No	Per-slot personalization status
`chuidWritten`, `cccWritten`, `printedInfoWritten`	bool	No	Data-object write flags
`pinSet`, `pukSet`, `mgmtKeyRotated`	bool	No	Credential state flags
`dryRun`	bool	No	True for simulation runs
`durationMs`	int	No	Personalization duration
`timestampUtc`	string	Yes	ISO-8601 (round-trip "o") timestamp

*At least one of cardSerial or personalizerId is required. Common errors: 9131, 9224, 9999.

piv_escrow_puk

Sends the card PUK to the server for encrypted storage. The plaintext PUK is never echoed back.

Type: piv_escrow_puk
Permission Required: PivEscrowPuk

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_escrow_puk"`
`psn`	string	Yes	Printed serial number of the PIV device
`puk`	string	No	Plaintext PUK; empty = server generates and stores a random PUK

Success Response:

{
    "type": "piv_escrow_puk",
    "errorCode": 0,
    "errorMessage": "OK",
    "serverGenerated": false
}

Common errors: 9131, 9021, 9010.

piv_batch_audit_add / piv_batch_audit_list / piv_batch_audit_get / piv_batch_audit_delete

Record, list, retrieve, and soft-delete batch-provisioning audit runs (single-card = batch of 1). Secret material is never transmitted.

Permission Required: PivBatchAudit

Type	Description
`piv_batch_audit_add`	Records a run summary and per-card `items[]`
`piv_batch_audit_list`	Filtered list of run summaries (`fromUtc`, `toUtc`, `status`, `flow`, `serialNumber`, `maxRows`)
`piv_batch_audit_get`	Single run header plus per-card items (`batchId`)
`piv_batch_audit_delete`	Soft-deletes a run (`batchId`)

piv_pin_reset_voucher_create / piv_pin_reset_voucher_verify / piv_pin_reset_complete

Three-step, single-use, time-limited PIN-reset voucher flow. The plaintext voucher is returned once; only its SHA-256 hash is persisted.

Permission Required: PivPinReset

Type	Description
`piv_pin_reset_voucher_create`	Issues a voucher (`username`, optional `ttlMinutes`); returns `voucher`, `expiresAt`, `ttlMinutes`
`piv_pin_reset_voucher_verify`	Verifies (`voucher`, optional `psn`); returns bound identity and (if escrowed) plaintext `puk`
`piv_pin_reset_complete`	Closes the voucher (`voucher`, `result` = success/failure) ? Consumed (2) or Revoked (3)

Common errors: 9131, 9207, 9999.

piv_activation_factory_data_create / piv_activation_factory_data_verify / piv_activation_complete

Three-step first-PIN activation voucher flow (Shape A). For IDEMIA cards, verify returns derived factory PUK, 9B management key, and factory PIN from the card CF context object.

Permission Required: PivActivation

Type	Description
`piv_activation_factory_data_create`	Issues a voucher (`username`, optional `ttlMinutes`)
`piv_activation_factory_data_verify`	Verifies (`voucher`, `psn`, optional `cardType`, `cardContextCf`); returns bound identity and factory secrets
`piv_activation_complete`	Closes the voucher (`voucher`, `result` = success/failure) ? Consumed (2) or Revoked (3)

piv_identity_proofing_status / piv_identity_proofing_submit

Query required IAL and current proofing status, and submit operator-attested (text-only) evidence for server-side re-scoring.

Type	Description
`piv_identity_proofing_status`	Returns `requiredAssuranceLevel`, `proofingRequired`, `proofingSatisfied`, `achievedAssuranceLevel`, `decision`
`piv_identity_proofing_submit`	Submits `evidence[]` + `attestation`; server re-scores and returns `decision`, `passed`, `reasons[]`

piv_iot_authorize

Authorizes an IoT device action using a PIV workstation session token (Phase 14).

Type: piv_iot_authorize

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piv_iot_authorize"`
`iotDeviceKey`	string	Yes	Device key from the admin portal
`sessionToken`	string	Yes	Session token from a successful `piv_auth`
`action`	string	Yes	Action to authorize (e.g. "unlock")

Common errors: 9215, 9211, 9214, 9212, 9213, 9216.

piviotauthorize_cellular

Authorizes a cellular IoT device action, with optional device mTLS, GPS telemetry, and a signed offline authorization bundle (Phase 15).

Type: piviotauthorize_cellular

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piviotauthorize_cellular"`
`userToken`	string	Yes	Session token from a successful `piv_auth`
`action`	string	Yes	Action to authorize
`deviceInfo`	object	No*	Cellular telemetry (IMEI, ICCID, GPS, battery, signal)

*Required when the device is not authenticating via mTLS. Common errors: 9215, 9211, 9214, 9212, 9217, 9218, 9219.

piviot_offline_sync

Uploads queued offline authorization events when a cellular device reconnects (Phase 15).

Type: piviot_offline_sync

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"piviot_offline_sync"`
`deviceKey`	string	Yes	Reporting device key
`events`	array	Yes	Offline events (each with `OfflineAuthBundleHash`)

Common errors: 9211.

Token Inventory APIs

Token order and inventory lifecycle management (spec section 10), implemented by the AuthServerRestApi.TokenOrder and AuthServerRestApi.TokenInventory partial classes.

token_order_find

Looks up a token order by id or order number, or lists orders with filters.

Type: token_order_find
Permission Required: TokenOrderFind

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"token_order_find"`
`tokenOrderId`	int	No*	Numeric order id
`orderNumber`	string	No*	Human-readable order number
`listMode`	bool	No	When true, returns an `orders[]` array using filter fields (`status`, `manufacturerId`, `productId`, `orderType`, `orderedOnDate`)

*Provide tokenOrderId or orderNumber for single-order lookup. Common errors: 9131, 9230.

token_order_register

Registers a shipment of tokens against an existing order; optionally creates device rows and activation notifications.

Type: token_order_register
Permission Required: TokenOrderRegister

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"token_order_register"`
`tokenOrderId`	int	Yes	Existing order id
`items`	array	Yes	One entry per physical token
`shipmentId`	string	No	Shipment reference
`vendor`	string	No	Vendor/manufacturer name
`createDevice`	string	No	`"true"` to provision device rows
`activationTemplateName`	string	No	Notification template name
`tokenImportType`	string	No	`Fido2` (default) or `Piv`

Success Response:

{
    "type": "token_order_register",
    "errorCode": 0,
    "errorMessage": "OK",
    "registeredCount": 10,
    "devicesCreatedCount": 10,
    "pivDevicesCreatedCount": 0,
    "activationsSentCount": 10,
    "items": [ ... ]
}

Common errors: 9131, 9230, 9231, 9236.

token_inventory_find

Lists inventoried tokens by partner with optional filters.

Type: token_inventory_find
Permission Required: TokenInventoryFind

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"token_inventory_find"`
`serialNumber`	string	No	Exact-match serial filter
`status`	string	No	`New`, `Assigned`, `Provisioned`, etc.
`productId`	string	No	Product id filter
`tokenOrderId`	int	No	Restrict to children of a parent order

An empty tokens[] array is a normal "no matches" result. Common errors: 9131.

token_inventory_assign

Assigns an inventoried token to a user.

Type: token_inventory_assign
Permission Required: TokenInventoryAssign

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"token_inventory_assign"`
`serialNumber`	string	Yes	Inventory row to assign
`username`	string	Yes	Target user login name
`devicePsn`	string	No	Existing device PSN to link

Common errors: 9131, 9133, 9232, 9233, 9235, 9237.

token_inventory_unassign

Releases a token back into inventory.

Type: token_inventory_unassign
Permission Required: TokenInventoryUnassign

Request Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"token_inventory_unassign"`
`serialNumber`	string	Yes	Inventory row to release

Common errors: 9131, 9232, 9234, 9235.

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
9124	DeviceNotAssigned	Device is not assigned to a user
9128	DeviceExpired	Token has expired
9129	RoleViolation	Administrative role violation / database error
9130	DeviceNotEnabled	Device is not enabled
9131	ApiAccessViolation	API permission denied
9132	PushTokenAlreadyExistsForDevice	Push token already exists for device
9133	PartnerUserNotFound	User not found
9134	PartnerNotFound	Partner/organization not found

PIV Smart Card Error Codes

Code	Name	Description
9200	PivCertificateInvalid	Certificate invalid / bad base64
9201	PivCertificateExpired	Certificate has expired
9202	PivCertificateRevoked	Certificate has been revoked
9203	PivCertificateNotTrusted	Certificate chain not trusted
9204	PivChallengeInvalid	Challenge signature verification failed
9205	PivSessionExpired	PIV enrollment/auth session expired
9206	PivNoCertificatesEnrolled	No certificates enrolled for user
9207	PivPolicyViolation	PIV not enabled / policy violation
9208	PivRevocationCheckFailed	Revocation (CRL/OCSP) check failed
9209	PivKeySlotNotAllowed	PIV key slot not permitted
9210	PivCertificateAlreadyEnrolled	Certificate already enrolled
9223	PivEnrollAdminBatch	Admin batch enrollment audit code
9224	PivPersonalizationFailed	Chip personalization failed

PIV IoT Error Codes

Code	Name	Description
9211	PivIotDeviceNotFound	IoT device / device key not found
9212	PivIotActionNotAllowed	Action not in device's AllowedActions
9213	PivIotKeySlotNotAllowed	IoT key slot not permitted
9214	PivIotDeviceDisabled	IoT device is disabled
9215	PivIotSessionExpired	IoT session token expired/invalid
9216	PivIotDeviceKeyInvalid	IoT device key invalid
9217	PivIotMtlsRequired	mTLS required but no client certificate
9218	PivIotDeviceCertificateInvalid	Device certificate hash mismatch
9219	PivIotDeviceCertificateExpired	Device certificate expired
9220	PivIotOfflineBundleInvalid	Offline authorization bundle invalid
9221	PivIotOfflineBundleExpired	Offline authorization bundle expired
9222	PivIotGeofenceViolation	Geofence restriction violated

Token Inventory Error Codes

Code	Name	Description
9230	TokenOrderNotFound	Token order not found
9231	TokenInventoryDuplicateSerial	Duplicate serial number in inventory
9232	TokenInventoryNotFound	Inventory row not found
9233	TokenInventoryAlreadyAssigned	Token already assigned
9234	TokenInventoryNotAssigned	Token not currently assigned
9235	TokenInventoryInvalidStatus	Invalid status transition
9236	TokenOrderNotificationFailed	Order activation notification failed
9237	TokenInventoryDeviceNotFound	Linked device PSN not found

Client-Side Error Codes

Code	Name	Description
9997	SyncEventLogFormatNotSupported	Event log format not supported (client)
9998	NetworkError / ServerConnectivityFailure	Server unreachable / network failure (client)
9999	DiagnosticTrace	Generic data missing/incorrect

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
`piv_pre_enroll`, `piv_enroll`	PivEnroll	54
`piv_pre_auth`, `piv_auth`, `piv_header_auth`	PivAuth	55
`piv_admin_enroll`	PivAdminEnroll	61
`piv_find_device`	PivFindDevice	-
`piv_delete_device`	PivDeleteDevice	-
`piv_log_perso`	PivLogPerso	-
`piv_escrow_puk`	PivEscrowPuk	-
`piv_batch_audit_*`	PivBatchAudit	-
`piv_pin_reset_*`	PivPinReset	-
`piv_activation_*`	PivActivation	-
`token_order_find`	TokenOrderFind	-
`token_order_register`	TokenOrderRegister	-
`token_inventory_find`	TokenInventoryFind	-
`token_inventory_assign`	TokenInventoryAssign	-
`token_inventory_unassign`	TokenInventoryUnassign	-

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
`piv_pre_enroll`	PIV_PRE_ENROLL
`piv_enroll`	PIV_ENROLL
`piv_pre_auth`	PIV_PRE_AUTH
`piv_auth`	PIV_AUTH
`piv_header_auth`	PIV_HEADER_AUTH
`piv_find_device`	PIV_FIND_DEVICE
`piv_delete_device`	PIV_DELETE_DEVICE
`piv_admin_enroll`	PIV_ADMIN_ENROLL
`piv_log_perso`	PIV_LOG_PERSO
`piv_escrow_puk`	PIV_ESCROW_PUK
`piv_batch_audit_add`	PIV_BATCH_AUDIT_ADD
`piv_batch_audit_list`	PIV_BATCH_AUDIT_LIST
`piv_batch_audit_get`	PIV_BATCH_AUDIT_GET
`piv_batch_audit_delete`	PIV_BATCH_AUDIT_DELETE
`piv_identity_proofing_status`	PIV_IDENTITY_PROOFING_STATUS
`piv_identity_proofing_submit`	PIV_IDENTITY_PROOFING_SUBMIT
`piv_pin_reset_voucher_create`	PIV_PIN_RESET_VOUCHER_CREATE
`piv_pin_reset_voucher_verify`	PIV_PIN_RESET_VOUCHER_VERIFY
`piv_pin_reset_complete`	PIV_PIN_RESET_COMPLETE
`piv_activation_factory_data_create`	PIV_ACTIVATION_FACTORY_DATA_CREATE
`piv_activation_factory_data_verify`	PIV_ACTIVATION_FACTORY_DATA_VERIFY
`piv_activation_complete`	PIV_ACTIVATION_COMPLETE
`piv_iot_authorize`	PIV_IOT_AUTHORIZE
`piviotauthorize_cellular`	PIV_IOT_AUTHORIZE_CELLULAR
`piviot_offline_sync`	PIV_IOT_OFFLINE_SYNC
`token_order_find`	TOKEN_ORDER_FIND
`token_order_register`	TOKEN_ORDER_REGISTER
`token_inventory_find`	TOKEN_INVENTORY_FIND
`token_inventory_assign`	TOKEN_INVENTORY_ASSIGN
`token_inventory_unassign`	TOKEN_INVENTORY_UNASSIGN

© 2013–2026 SurePassID. All rights reserved. Protected by patents pending. SurePassID, the SurePassID logo and design, and Secure SSO are registered trademarks or trademarks of SurePassID, Corp. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

SurePassID 360 Central Avenue #800 St. Petersburg, FL 33701 USA +1 (888) 200-8144 surepassid.com