API Document
Version
v1.1.1v1.1.0Fix some API parameters error.
v1.0.1Add Mobile Authenticator app relative API and error codes.
Fix FIDO2 verify api name typo.
Introduction
This section provides an overview of the functionality of the AuthFi API.
The Relying Party is tasked with implementing the request and response mechanisms necessary for establishing communication with the AuthFi server.
Overview
Interacting with the API endpoints requires a valid API Key, which can be obtained from the AuthFi dashboard.
Key points to remember include:
- Secure Communication: The AuthFi API exclusively supports communication over HTTPS.
- Response Format: Responses to requests are formatted in JSON. Error responses include a
"code": error_code
key. - Request Methods: The desired action is determined by the request method (verb). Using the
GET
method retrieves information from AuthFi, while usingPOST
introduces new data. - Status Codes: Each API call returns a corresponding HTTP status code. A
2XX
code signifies successful execution, while4XX
or5XX
codes indicate errors from either the client or AuthFi's servers, respectively.
WARNING
It is crucial to include the AT-X-KEY
in the HTTP request header for all requests. Your API Key should be used as the content for this header.
Sample Code
You can explore the provided links below to access sample code that demonstrates the integration of the AuthFi API into your service:
Passkey
Not Passkey
FIDO2 Security Key register
Step 1 - Register a FIDO2 Security Key
/{API_ACCESSPOINT}/api/v1/webauthn/registration
Send authenticator register parameters to AuthFi server to obtain FIDO2 Security Key register request.
If you use ATKey as Security Key
Please use following value:
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"residentKey": "required",
"requireResidentKey": true,
"userVerification": "required"
}
"attestation": "direct"
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"residentKey": "required",
"requireResidentKey": true,
"userVerification": "required"
}
"attestation": "direct"
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"params": {
"user": {
"name": "[email protected]",
"displayName": "Foo Bar",
},
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"residentKey": "preferred",
"requireResidentKey": true,
"userVerification": "required"
},
"attestation": "direct"
}
}
{
"params": {
"user": {
"name": "[email protected]",
"displayName": "Foo Bar",
},
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"residentKey": "preferred",
"requireResidentKey": true,
"userVerification": "required"
},
"attestation": "direct"
}
}
interface Schema
{
params: {
user: {
// User account
name: string
// User name
displayName: string
}
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// 'required' - authenticator must create a client side resident private key when authenticator support this feature. If authenticator not support, this will rais an error when calling navigator.credentials.create()
// 'preferred' - authenticator will create a client side resident private key when authenticator support this feature.
// 'discouraged' - not create client side resident private key
residentKey: 'required' | 'preferred' | 'discouraged'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
interface Schema
{
params: {
user: {
// User account
name: string
// User name
displayName: string
}
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// 'required' - authenticator must create a client side resident private key when authenticator support this feature. If authenticator not support, this will rais an error when calling navigator.credentials.create()
// 'preferred' - authenticator will create a client side resident private key when authenticator support this feature.
// 'discouraged' - not create client side resident private key
residentKey: 'required' | 'preferred' | 'discouraged'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"fido_register_request": {
"rp": {
"id": "example.com",
"name": "example website"
},
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"displayName": "Foo Bar"
},
"challenge": "abcdef0123456789",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"timeout": 900000,
"excludeCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"extensions": {},
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"residentKey": "preferred",
"requireResidentKey": true,
"userVerification": "required"
},
"attestation": "direct"
}
}
{
"code": 0,
"fido_register_request": {
"rp": {
"id": "example.com",
"name": "example website"
},
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"displayName": "Foo Bar"
},
"challenge": "abcdef0123456789",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"timeout": 900000,
"excludeCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"extensions": {},
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"residentKey": "preferred",
"requireResidentKey": true,
"userVerification": "required"
},
"attestation": "direct"
}
}
interface Schema
{
// API result status code
code: number
fido_register_request: {
rp: {
// RP domain name
id: string
// website name
name: string
}
user: {
// base64-url format user ID byte array source
id: string
// User account. Usually email format
name: string
// User name
displayName: string
}
// base64-url format display byte array source
challenge: string
pubKeyCredParams: {
// Defines the valid credential types
type: 'public-key'
// COSE Algorithms registry
alg: number
}[]
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
excludeCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// 'required' - authenticator must create a client side resident private key when authenticator support this feature. If authenticator not support, this will rais an error when calling navigator.credentials.create()
// 'preferred' - authenticator will create a client side resident private key when authenticator support this feature
// 'discouraged' - not create client side resident private key
residentKey: 'required' | 'preferred' | 'discouraged'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
interface Schema
{
// API result status code
code: number
fido_register_request: {
rp: {
// RP domain name
id: string
// website name
name: string
}
user: {
// base64-url format user ID byte array source
id: string
// User account. Usually email format
name: string
// User name
displayName: string
}
// base64-url format display byte array source
challenge: string
pubKeyCredParams: {
// Defines the valid credential types
type: 'public-key'
// COSE Algorithms registry
alg: number
}[]
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
excludeCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// 'required' - authenticator must create a client side resident private key when authenticator support this feature. If authenticator not support, this will rais an error when calling navigator.credentials.create()
// 'preferred' - authenticator will create a client side resident private key when authenticator support this feature
// 'discouraged' - not create client side resident private key
residentKey: 'required' | 'preferred' | 'discouraged'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
Step 2 - Register FIDO2 Security Key Attestation response to server
/{API_ACCESSPOINT}/api/v1/webauthn/registration
Receive FIDO request from AuthFi server and return to client, so client browser send request to FIDO2 Security Key, then get FIDO2 response and update to AuthFi server.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"fido_register_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"attestationObject": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789",
}
}
}
{
"fido_register_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"attestationObject": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789",
}
}
}
interface Schema
{
fido_register_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
}
response: {
// base64-url format string of attestationObject byte array. Response from authenticator. Need convert by client web or server
attestationObject: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
}
interface Schema
{
fido_register_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
}
response: {
// base64-url format string of attestationObject byte array. Response from authenticator. Need convert by client web or server
attestationObject: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
}
Response 201
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
Passwordless logon - include Passkey
Step 1 - Login with a FIDO2 Security Key
/{API_ACCESSPOINT}/api/v1/webauthn/login
Send authenticator login parameters to AuthFi server to obtain FIDO2 Security Key login request.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request sample (application/json)
{
"params": {
"userVerification": "required"
}
}
{
"params": {
"userVerification": "required"
}
}
interface Schema
{
params: {
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
}
interface Schema
{
params: {
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
}
Response 200 (application/json)
{
"code": 0,
"fido_login_request": {
"challenge": "abcdef0123456789",
"timeout": 900000,
"rpId": "example.com",
"allowCredentials": [],
"userVerification": "required",
"extensions": {}
}
}
{
"code": 0,
"fido_login_request": {
"challenge": "abcdef0123456789",
"timeout": 900000,
"rpId": "example.com",
"allowCredentials": [],
"userVerification": "required",
"extensions": {}
}
}
interface Schema
{
// API result status code
code: number
fido_login_request: {
// base64-url format display byte array source
challenge: string
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number,
// RP domain name
rpId: string
allowCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
}
}
interface Schema
{
// API result status code
code: number
fido_login_request: {
// base64-url format display byte array source
challenge: string
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number,
// RP domain name
rpId: string
allowCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
}
}
Step 2 - Login Authentication response to server
/{API_ACCESSPOINT}/api/v1/webauthn/login
Receive FIDO request from AuthFi server and return to client, so client browser send request to FIDO2 Security Key, then get FIDO2 response and update to AuthFi server.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"fido_login_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}
{
"fido_login_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}
interface Schema
{
fido_login_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server
authenticatorData: string
// base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server
signature: string
// base64-url format string of userHandle byte array. Response from authenticator. Need convert by client web or server. In some case value will be null object
userHandle: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
// content with FIDO2 extions
getClientExtensionResults: { [x: string]: any }
}
}
interface Schema
{
fido_login_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server
authenticatorData: string
// base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server
signature: string
// base64-url format string of userHandle byte array. Response from authenticator. Need convert by client web or server. In some case value will be null object
userHandle: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
// content with FIDO2 extions
getClientExtensionResults: { [x: string]: any }
}
}
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"user": {
"id": "abcdef0123456789",
"name": "[email protected]"
},
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"user": {
"id": "abcdef0123456789",
"name": "[email protected]"
},
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number,
user: {
// base64-url format user ID byte array source
id: string
// User account. Usually email format
name: string
}
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string,
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
interface Schema
{
// API result status code
code: number,
user: {
// base64-url format user ID byte array source
id: string
// User account. Usually email format
name: string
}
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string,
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
MFA - include Passkey
Step 1 - Identity Verify with FIDO2 Device
/{API_ACCESSPOINT}/api/v1/webauthn/verification
Get FIDO2 authentication request from AuthFi server for specific user.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request sample (applicatoin/json)
{
"uId": "[email protected]",
"params": {
"userVerification": "required"
}
}
{
"uId": "[email protected]",
"params": {
"userVerification": "required"
}
}
interface Schema
{
// User account. Usually email format
uId: string
params: {
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
}
interface Schema
{
// User account. Usually email format
uId: string
params: {
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
}
Response 200 (application/json)
{
"code": 0,
"fido_auth_request": {
"challenge": "abcdef0123456789",
"timeout": 12345,
"rpId": "example.com",
"allowCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"userVerification": "required",
"extensions": {}
}
}
{
"code": 0,
"fido_auth_request": {
"challenge": "abcdef0123456789",
"timeout": 12345,
"rpId": "example.com",
"allowCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"userVerification": "required",
"extensions": {}
}
}
interface Schema
{
// API result status code
code: number,
fido_auth_request: {
// base64-url format display byte array source
challenge: string
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
// RP domain name
rpId: string
allowCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
}
}
interface Schema
{
// API result status code
code: number,
fido_auth_request: {
// base64-url format display byte array source
challenge: string
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
// RP domain name
rpId: string
allowCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
}
}
Step 2 - Identity Verify Authentication response to server
/{API_ACCESSPOINT}/api/v1/webauthn/verification
After passing FIDO2 request to Security Key and receive FIDO2 response.
Send FIDO2 response back to AuthFi server to finish verifying identity.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request sample (applicatoin/json)
{
"fido_auth_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}
{
"fido_auth_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}
interface Schema
{
fido_auth_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server
authenticatorData: string
// base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server
signature: string
// base64-url format string of userHandle byte array. Response from authenticator. Need convert by client web or server. In some case value will be null object
userHandle: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
// content with FIDO2 extions
getClientExtensionResults: { [x: string]: any }
}
}
interface Schema
{
fido_auth_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server
authenticatorData: string
// base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server
signature: string
// base64-url format string of userHandle byte array. Response from authenticator. Need convert by client web or server. In some case value will be null object
userHandle: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
// content with FIDO2 extions
getClientExtensionResults: { [x: string]: any }
}
}
Response 200 (application/json)
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
Management
Get register user list
/{API_ACCESSPOINT}/api/v1/users{?page,size}
Get registered user information from AuthFi.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
page
- number (optional)Page index of query informations.
e.g.1
size
- number (optional)Records max size of response array, range from 20 to 100, default is 20.
e.g.20
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"total": 1,
"users": [
{
"id": "abcdef0123456789",
"name": "[email protected]",
"state": "activate",
"create_time": 12345,
"update_time": 12345
}
]
}
{
"code": 0,
"total": 1,
"users": [
{
"id": "abcdef0123456789",
"name": "[email protected]",
"state": "activate",
"create_time": 12345,
"update_time": 12345
}
]
}
interface Schema
{
// API result status code
code: number
// Number of register users
total: number
users: {
// User ID in AuthFi server
id: string
// User name
name: string
// User status of permission use FIDO2 authentication
state: 'activate' | 'suspend'
// UTC time when user information registered on AuthFi
create_time: number
// UTC time when user information updated on AuthFi
update_time: number
}[]
}
interface Schema
{
// API result status code
code: number
// Number of register users
total: number
users: {
// User ID in AuthFi server
id: string
// User name
name: string
// User status of permission use FIDO2 authentication
state: 'activate' | 'suspend'
// UTC time when user information registered on AuthFi
create_time: number
// UTC time when user information updated on AuthFi
update_time: number
}[]
}
Change target user state
/{API_ACCESSPOINT}/api/v1/users/{userId}
Change user status with activate
and suspend
to allowed or to blocked user to use FIDO2 authentication.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
userId
- stringThe user ID stored in AuthFi server.
e.g.abcdefgh0123456789
Request sample (application/json)
{
"state": "activate"
}
{
"state": "activate"
}
interface Schema
{
// New status for user
status: 'activate' | 'suspend'
}
interface Schema
{
// New status for user
status: 'activate' | 'suspend'
}
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"state": "activate",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"state": "activate",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number
user: {
// User ID in AuthFi server
id: string
// User name
name: string
// User status of permission use FIDO2 authentication
state: 'activate' | 'suspend'
// UTC time when user information registered on AuthFi
create_time: number
// UTC time when user information updated on AuthFi
update_time: number
}
}
interface Schema
{
// API result status code
code: number
user: {
// User ID in AuthFi server
id: string
// User name
name: string
// User status of permission use FIDO2 authentication
state: 'activate' | 'suspend'
// UTC time when user information registered on AuthFi
create_time: number
// UTC time when user information updated on AuthFi
update_time: number
}
}
Delete target user
/{API_ACCESSPOINT}/api/v1/users/{userId}
To delete a registered user and all user registered keys.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
userId
- stringThe user ID stored in AuthFi server.
e.g.abcdefgh0123456789
Response 200 (application/json)
{
"code": 0,
"deleteUser": {
"id": "abcdef0123456789",
"name": "[email protected]"
},
"deleteUserRegisterKeys": 1
}
{
"code": 0,
"deleteUser": {
"id": "abcdef0123456789",
"name": "[email protected]"
},
"deleteUserRegisterKeys": 1
}
interface Schema
{
// API result status code
code: number
deleteUser: {
// User ID in AuthFi server
id: string
// User name
name: string
}
// Number of delete user register keys was deleted
deleteUserRegisterKeys: number
}
interface Schema
{
// API result status code
code: number
deleteUser: {
// User ID in AuthFi server
id: string
// User name
name: string
}
// Number of delete user register keys was deleted
deleteUserRegisterKeys: number
}
Get a user registered key information
/{API_ACCESSPOINT}/api/v1/users/{userId}/keys
Get all user registered security keys information.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
userId
- stringThe user ID from AuthFi server.
e.g.abcdefgh0123456789
Response 200 (applicatoin/json)
{
"code": 0,
"total": 1,
"keys": [
{
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
]
}
{
"code": 0,
"total": 1,
"keys": [
{
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
]
}
interface Schema
{
// API result status code
code: number
// key count, max size 10
total: number
keys: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}[]
}
interface Schema
{
// API result status code
code: number
// key count, max size 10
total: number
keys: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}[]
}
Set a friendly name to register security key
/{API_ACCESSPOINT}/api/v1/users/{userId}/keys/{id}
Set a easily readable name to identify different key.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
userId
- stringThe user ID from AuthFi server.
e.g.abcdefgh0123456789
id
- stringThe Credential ID from AuthFi server.
e.g.abcdefgh0123456789
Request sample (application/json)
{
"name": "New key name"
}
{
"name": "New key name"
}
interface Schema
{
// for human friendly reading to specify securty key
name: string
}
interface Schema
{
// for human friendly reading to specify securty key
name: string
}
Response 200 (application/json)
{
"code": 0,
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "New key name",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "New key name",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number,
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
interface Schema
{
// API result status code
code: number,
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
Delete a user registered security key
/{API_ACCESSPOINT}/api/v1/users/{userId}/keys/{id}
Delete a registered security key.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
userId
- stringThe user ID from AuthFi server.
e.g.abcdefgh0123456789
id
- stringThe Credential ID from AuthFi server.
e.g.abcdefgh0123456789
Response 200 (application/json)
{
"code": 0,
"deleteKeys": 1
}
{
"code": 0,
"deleteKeys": 1
}
interface Schema
{
// API result status code
code: number
// delete register keys count
deleteKeys: number
}
interface Schema
{
// API result status code
code: number
// delete register keys count
deleteKeys: number
}
Non-Passkey Mobile App API
Get a QRCode for register with authenticator app
/{API_ACCESSPOINT}/api/v1/mobile/registration/qrcode
Get a QRCode to display on PC browser side for registration with authenticator app (e.g. AT.AuthFi Authenticator).
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request sample
Content-Type: application/json
Content-Type: application/json
{
"params": {
"user": "[email protected]",
"path": "/PATH_NAME/HTML_FILE_NAME_or_API_NAME_for_getting_html_texts"
}
}
{
"params": {
"user": "[email protected]",
"path": "/PATH_NAME/HTML_FILE_NAME_or_API_NAME_for_getting_html_texts"
}
}
interface Schema
{
params: {
// The user email to register with authenticator app
user: string
// The path to access mobile register page, ex: /app/register.html
path: string
}
}
interface Schema
{
params: {
// The user email to register with authenticator app
user: string
// The path to access mobile register page, ex: /app/register.html
path: string
}
}
Response 201
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"token": "abcdef0123456789",
"image": "abcdef0123456789",
"expire_at": 12345
}
{
"code": 0,
"token": "abcdef0123456789",
"image": "abcdef0123456789",
"expire_at": 12345
}
interface Schema
{
// API result status code
code: number
// QRCode ID
token: string
// base64 form string to present QRCode in PNG image file
image: string
// UTC time value in future that QRCode will expire
expire_at: number
}
interface Schema
{
// API result status code
code: number
// QRCode ID
token: string
// base64 form string to present QRCode in PNG image file
image: string
// UTC time value in future that QRCode will expire
expire_at: number
}
Poll authenticator app register result
/{API_ACCESSPOINT}/api/v1/mobile/registration/result{?token}
Get authenticator app register result on PC browser side.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
token
- stringThe QRCode token from AuthFi server.
e.g.abcdefgh0123456789
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"app_result": 1
}
{
"code": 0,
"app_result": 1
}
interface Schema
{
// API result status code
code: number
// authenticator app registration result
// 0: authenticator register success
// 1: wait for authenticator app to finish register
// 2: authenticator register fail
app_result: 0 | 1 | 2
}
interface Schema
{
// API result status code
code: number
// authenticator app registration result
// 0: authenticator register success
// 1: wait for authenticator app to finish register
// 2: authenticator register fail
app_result: 0 | 1 | 2
}
Step 1 - Register with authenticator app
/{API_ACCESSPOINT}/api/v1/mobile/registration
Send authenticator register parameters to AuthFi server to obtain FIDO2 Security Key register request.
If you use authenticator app as Security Key
Please use following value:
authenticatorSelection: {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
attestation: "direct"
authenticatorSelection: {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
attestation: "direct"
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"params": {
"token": "abcdef0123456789",
"user": {
"name": "[email protected]",
"displayName": "Foo Bar"
},
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
"attestation": "direct"
}
}
{
"params": {
"token": "abcdef0123456789",
"user": {
"name": "[email protected]",
"displayName": "Foo Bar"
},
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
"attestation": "direct"
}
}
interface Schema
{
params: {
// QRCode ID
token: string
user: {
// User account
name: string
// User name
displayName: string
}
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
},
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
interface Schema
{
params: {
// QRCode ID
token: string
user: {
// User account
name: string
// User name
displayName: string
}
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
},
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"fido_register_request": {
"rp": {
"id": "example.com",
"name": "example website"
},
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"displayName": "Foo Bar"
},
"challenge": "abcdef0123456789",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"timeout": 900000,
"excludeCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"extensions": {},
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
"attestation": "direct"
}
}
{
"code": 0,
"fido_register_request": {
"rp": {
"id": "example.com",
"name": "example website"
},
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"displayName": "Foo Bar"
},
"challenge": "abcdef0123456789",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"timeout": 900000,
"excludeCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"extensions": {},
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
"attestation": "direct"
}
}
interface Schema
{
// API result status code
code: number
fido_register_request: {
rp: {
// RP domain name
id: string
// website name
name: string
}
user: {
// base64-url format user ID byte array source
id: string
// User account. Usually email format
name: string
// User name.
displayName: string
}
// base64-url format display byte array source
challenge: string,
pubKeyCredParams: {
// Defines the valid credential types
type: 'public-key'
// COSE Algorithms registry
alg: number
}[]
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
excludeCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
interface Schema
{
// API result status code
code: number
fido_register_request: {
rp: {
// RP domain name
id: string
// website name
name: string
}
user: {
// base64-url format user ID byte array source
id: string
// User account. Usually email format
name: string
// User name.
displayName: string
}
// base64-url format display byte array source
challenge: string,
pubKeyCredParams: {
// Defines the valid credential types
type: 'public-key'
// COSE Algorithms registry
alg: number
}[]
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
excludeCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// This member contains additional parameters requesting additional processing by the client and authenticator
extensions: { [x: string]: any }
authenticatorSelection: {
// Option describe authenticator type
// 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Key
// 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID
authenticatorAttachment: 'cross-platform' | 'platform'
// When the requireResidentKey attribute is true, the authenticator must create a client side resident private key
requireResidentKey: boolean
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
// Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation
// 'none': This value indicates that the Relying Party is not interested in authenticator attestation
// 'indirect': This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a heterogeneous ecosystem
// 'direct': This value indicates that the Relying Party wants to receive the attestation statement as generated by the authenticator
attestation: 'none' | 'indirect' | 'direct'
}
}
Step 2 - Register with authenticator app
/{API_ACCESSPOINT}/api/v1/mobile/registration
Receive FIDO request from AuthFi server and return to client, so authenticator app send request to FIDO2 Security Key, then get FIDO2 response and update to AuthFi server.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"token": "abcdef0123456789",
"fido_register_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"attestationObject": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789",
}
}
}
{
"token": "abcdef0123456789",
"fido_register_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"attestationObject": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789",
}
}
}
interface Schema
{
// QRCode ID
token: string
fido_register_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of attestationObject byte array. Response from authenticator. Need convert by client web or server
attestationObject: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
}
}
interface Schema
{
// QRCode ID
token: string
fido_register_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of attestationObject byte array. Response from authenticator. Need convert by client web or server
attestationObject: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
}
}
Response 201
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
Get just registered user name
/{API_ACCESSPOINT}/api/v1/mobile/registration/user{?token}
For authenticator app to get register user name for display on main menu.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
token
- stringThe QRCode token from AuthFi server.
e.g.abcdefgh0123456789
Response 200
Content-Type: application/json
Content-Type: application/json
interface Schema
{
// API result status code
code: number
// User account. Usually email format
account: string
}
interface Schema
{
// API result status code
code: number
// User account. Usually email format
account: string
}
Get a QRCode for verify with authenticator app
/{API_ACCESSPOINT}/api/v1/mobile/verification/qrcode
On PC browser to get a QRCode for authenticator app to scan for FIDO authentication.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"params": {
"path": "/PATH_NAME/HTML_FILE_NAME_or_API_NAME_for_getting_html_texts"
}
}
{
"params": {
"path": "/PATH_NAME/HTML_FILE_NAME_or_API_NAME_for_getting_html_texts"
}
}
interface Schema
{
params: {
// The path to access mobile verify page, ex: /app/verify.html
path: string
}
}
interface Schema
{
params: {
// The path to access mobile verify page, ex: /app/verify.html
path: string
}
}
Response 201
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"token": "abcdef0123456789",
"image": "abcdef0123456789",
"expire_at": 12345
}
{
"code": 0,
"token": "abcdef0123456789",
"image": "abcdef0123456789",
"expire_at": 12345
}
interface Schema
{
// API result status code
code: number
// QRCode ID
token: string
// base64 form string to present QRCode in PNG image file
image: string
// UTC time value in future that QRCode will expire
expire_at: number
}
interface Schema
{
// API result status code
code: number
// QRCode ID
token: string
// base64 form string to present QRCode in PNG image file
image: string
// UTC time value in future that QRCode will expire
expire_at: number
}
Poll authenticator app verify result
/{API_ACCESSPOINT}/api/v1/mobile/verification/result{?token}
On PC browser to get authenticator app verify result.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
token
- stringThe QRCode token from AuthFi server.
e.g.abcdefgh0123456789
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"app_result": 1
}
{
"code": 0,
"app_result": 1
}
interface Schema
{
// API result status code
code: number
// authenticator app registration result
// 0: authenticator register success
// 1: wait for authenticator app to finish register
// 2: authenticator register fail
app_result: 0 | 1 | 2
}
interface Schema
{
// API result status code
code: number
// authenticator app registration result
// 0: authenticator register success
// 1: wait for authenticator app to finish register
// 2: authenticator register fail
app_result: 0 | 1 | 2
}
Step 1 - Verify with authenticator app
/{API_ACCESSPOINT}/api/v1/mobile/verification
For authenticator app to get FIDO2 authentication request from AuthFi server for specific user.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"uId": "[email protected]",
"token": "abcdef0123456789",
"params": {
"userVerification": "preferred"
}
}
{
"uId": "[email protected]",
"token": "abcdef0123456789",
"params": {
"userVerification": "preferred"
}
}
interface Schema
{
// User account. Usually email format
uId: string
// QRCode ID
token: string
params: {
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
}
interface Schema
{
// User account. Usually email format
uId: string
// QRCode ID
token: string
params: {
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
}
}
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"fido_auth_request": {
"challenge": "abcdef0123456789",
"timeout": 12345,
"rpId": "example.com",
"allowCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"userVerification": "preferred",
"extensions": {}
}
}
{
"code": 0,
"fido_auth_request": {
"challenge": "abcdef0123456789",
"timeout": 12345,
"rpId": "example.com",
"allowCredentials": [
{
"type": "public-key",
"id": "abcdef0123456789"
}
],
"userVerification": "preferred",
"extensions": {}
}
}
interface Schema
{
// API result status code
code: number
fido_auth_request: {
// base64-url format display byte array source
challenge: string
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
// RP domain name
rpId: string
allowCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
// This member contains additional parameters requesting additional processing by the client and authenticator.
extensions: { [x: string]: any }
}
}
interface Schema
{
// API result status code
code: number
fido_auth_request: {
// base64-url format display byte array source
challenge: string
// This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete
timeout: number
// RP domain name
rpId: string
allowCredentials: {
// Defines the valid credential types
type: 'public-key'
// Credential ID in UTF8 string type
id: string
}[]
// A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs
// 'required' - This value indicates that the Relying Party requires user verification for the operation and will fail the operation if the response does not have the UV flag set
// 'preferred' - This value indicates that the Relying Party prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set
// 'discouraged' - This value indicates that the Relying Party does not want user verification employed during the operation (e.g., in the interest of minimizing disruption to the user interaction flow)
userVerification: 'required' | 'preferred' | 'discouraged'
// This member contains additional parameters requesting additional processing by the client and authenticator.
extensions: { [x: string]: any }
}
}
Step 2 - Verify with authenticator app
/{API_ACCESSPOINT}/api/v1/mobile/verification
After passing FIDO2 request to authenticator app and receive FIDO2 response.
Send FIDO2 response back to AuthFi server to finish verifying identity.
Parameters
API_ACCESSPOINT
- stringThe API access point you receive when you apply a new RelyingParty.
e.g.abcdefgh0123456789
Request
Content-Type: application/json
Content-Type: application/json
{
"token": "abcdef0123456789",
"fido_auth_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}
{
"token": "abcdef0123456789",
"fido_auth_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}
interface Schema
{
// QRCode ID
token: string
fido_auth_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server
authenticatorData: string
// base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server
signature: string
// base64-url format string of userHandle byte array. Response from authenticator. Need convert by client web or server. In some case value will be null object
userHandle: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
// content with FIDO2 extions
getClientExtensionResults: { [x: string]: any }
}
}
interface Schema
{
// QRCode ID
token: string
fido_auth_response: {
// base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator
id: string
// base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server
rawId: string
// Defines the valid credential types
type: 'public-key'
response: {
// base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server
authenticatorData: string
// base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server
signature: string
// base64-url format string of userHandle byte array. Response from authenticator. Need convert by client web or server. In some case value will be null object
userHandle: string
// base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server
clientDataJSON: string
}
// content with FIDO2 extions
getClientExtensionResults: { [x: string]: any }
}
}
Response 200
Content-Type: application/json
Content-Type: application/json
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
}
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}
interface Schema
{
// API result status code
code: number
// base64-url format user ID byte array source
uid: string
key_info: {
// human readable ID string to identify credential in security key
credential_id: string
// counter for FIDO2 authentication
counter: number
// Human easily readble name to identify Security Key
name: string
// UTC time when the credential was create
create_time: number
// UTC time when the information in credential was update
update_time: number
}
}