AuthFi APIs
v1.1.1
Fix some API parameters error
v1.1.0
Add Mobile Authenticator app relative API and error codes
v1.0.1
Fix FIDO2 verify api name typo
Introduction
Following describe how AuthFI API work. Request and response are implement by Relying Party to communicate with AuthFi server.
Overview
-
You need a valid API Key to send requests to the API endpoints. You can get your key from the AuthFi dashboard.
-
The AuthFi API will only respond to secured communication done over HTTPS.
-
Response to every request is sent in JSON format. In case the API request results in an error, it is represented by an
"code": error_codekey in the JSON response. -
The request method (verb) determines the nature of action you intend to perform. A request made using the
GETmethod implies that you want to fetch something from AuthFi, andPOSTimplies you want to save something new to AuthFi. -
The API calls will respond with appropriate HTTP status codes for all requests. A
2XXindicates all went well, while4XXor5XXresponse codes indicate an error from the requesting client or our API servers respectively.
All the request need to add AT-X-KEY in http request header and set API Key as content
Sample Code
You can find sample code in below links to know how to implement AuthFi API in your service:
-
Passkey
- Web site sample - click here to GitHub
- Mobile application sample - click here to GitHub
- Mobile application library - click here to GitHub
-
Not Passkey
- Web site sample - click here to GitHub
- Mobile application sample - click here to GitHub
FIDO2 Security Key register - include Passkey ¶
Register a FIDO2 Security Key ¶
POST /abcdefgh0123456789/api/v1/webauthn/registration
Requests
Headers
Content-Type: application/jsonBody
{
"params": {
"user": {
"name": "[email protected]",
"displayName": "Foo Bar"
},
"authenticatorSelection": {
"authenticatorAttachment": "cross-platform",
"requireResidentKey": true,
"userVerification": "required"
},
"attestation": "direct"
}
}Schema
{
"type": "object",
"properties": {
"params": {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "User account."
},
"displayName": {
"type": "string",
"description": "User name."
}
}
},
"authenticatorSelection": {
"type": "object",
"properties": {
"authenticatorAttachment": {
"type": "string",
"description": "Option describe authenticator type. One of 'cross-platform', 'platform'. 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Kye. 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID"
},
"requireResidentKey": {
"type": "boolean",
"description": "When the requireResidentKey attribute is true, the authenticator must create a client side resident private key."
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
},
"attestation": {
"type": "string",
"description": "Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation. One of 'none', 'indirect', 'direct'. '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."
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"fido_register_request": {
"rp": {
"id": "www.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",
"requireResidentKey": true,
"userVerification": "required"
},
"attestation": "direct"
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"fido_register_request": {
"type": "object",
"properties": {
"rp": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "website hostname"
},
"name": {
"type": "string",
"description": "website name"
}
}
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"name": {
"type": "string",
"description": "User account. Usually email format."
},
"displayName": {
"type": "string",
"description": "User name."
}
}
},
"challenge": {
"type": "string",
"description": "base64-url format display byte array source."
},
"pubKeyCredParams": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"alg": {
"type": "number",
"description": "COSE Algorithms registry"
}
}
},...
]
},
"timeout": {
"type": "number",
"description": "This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete."
},
"excludeCredentials": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"id": {
"type": "string",
"description": "Credential ID in UTF8 string type"
}
}
},...
]
},
"extensions": {
"type": "object",
"properties": {},
"description": "This member contains additional parameters requesting additional processing by the client and authenticator."
},
"authenticatorSelection": {
"type": "object",
"properties": {
"authenticatorAttachment": {
"type": "string",
"description": "Option describe authenticator type. One of 'cross-platform', 'platform'. 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Kye. 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID"
},
"requireResidentKey": {
"type": "boolean",
"description": "When the requireResidentKey attribute is true, the authenticator must create a client side resident private key."
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
},
"attestation": {
"type": "string",
"description": "Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation. One of 'none', 'indirect', 'direct'. '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."
}
}
}
}
}Step 1POST/{API_ACCESSPOINT}/api/v1/webauthn/registration
Send authenticator register parameters to AuthFi server to obtain FIDO2 Security Key register request. And to use ATKey as Security Key. Please use following value
authenticatorSelection: {
"authenticatorAttachment": "cross-platform",
"requireResidentKey": true,
"userVerification": "required"
}attestation: "direct"
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Register FIDO2 Security Key Attestation response to server ¶
PUT /abcdefgh0123456789/api/v1/webauthn/registration
Requests
Headers
Content-Type: application/jsonBody
{
"fido_register_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"attestationObject": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789",
"getAuthenticatorData": {},
"getPublicKey": {},
"getPublicKeyAlgorithm": {},
"getTransports": {}
},
"getClientExtensionResults": {}
}
}Schema
{
"type": "object",
"properties": {
"fido_register_response": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator."
},
"rawId": {
"type": "string",
"description": "base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server."
},
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"response": {
"type": "object",
"properties": {
"attestationObject": {
"type": "string",
"description": "base64-url format string of attestationObject byte array. Response from authenticator. Need convert by client web or server."
},
"clientDataJSON": {
"type": "string",
"description": "base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server."
},
"getAuthenticatorData": {
"type": "object",
"description": "authenticator data object response by authenticator",
"properties": {}
},
"getPublicKey": {
"type": "object",
"description": "publickey object response by authenticator",
"properties": {}
},
"getPublicKeyAlgorithm": {
"type": "object",
"description": "publickey algorithm object response by authenticator",
"properties": {}
},
"getTransports": {
"type": "object",
"description": "transports object response by authenticator",
"properties": {}
}
}
},
"getClientExtensionResults": {
"type": "object",
"description": "content with FIDO2 extions",
"properties": {}
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"uid": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"key_info": {
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}
}
}Step 2PUT/{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.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Passwordless logon - include Passkey ¶
Login with a FIDO2 Security Key ¶
POST /abcdefgh0123456789/api/v1/webauthn/login
Requests
Headers
Content-Type: applicaton/jsonBody
{
"params": {
"userVerification": "required"
}
}Schema
{
"type": "object",
"properties": {
"params": {
"type": "object",
"properties": {
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
}
}
}Responses
Headers
Content-Type: applicaton/jsonBody
{
"code": 0,
"fido_login_request": {
"challenge": "abcdef0123456789",
"timeout": 900000,
"rpId": "www.example.com",
"allowCredentials": [],
"userVerification": "required",
"extensions": {}
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"fido_login_request": {
"type": "object",
"properties": {
"challenge": {
"type": "string",
"description": "base64-url format display byte array source."
},
"timeout": {
"type": "number",
"description": "This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete."
},
"rpId": {
"type": "string",
"description": "website hostname"
},
"allowCredentials": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"id": {
"type": "string",
"description": "Credential ID in UTF8 string type"
}
}
},...
]
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
},
"extensions": {
"type": "object",
"properties": {},
"description": "This member contains additional parameters requesting additional processing by the client and authenticator."
}
}
}
}
}Step 1POST/{API_ACCESSPOINT}/api/v1/webauthn/login
Send authenticator login parameters to AuthFi server to obtain FIDO2 Security Key login request.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Login Authentication response to server ¶
PUT /abcdefgh0123456789/api/v1/webauthn/login
Requests
Headers
Content-Type: application/jsonBody
{
"fido_login_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}Schema
{
"type": "object",
"properties": {
"fido_login_response": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator."
},
"rawId": {
"type": "string",
"description": "base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server."
},
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"response": {
"type": "object",
"properties": {
"authenticatorData": {
"type": "string",
"description": "base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server."
},
"signature": {
"type": "string",
"description": "base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server."
},
"userHandle": {
"type": "string",
"description": "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."
},
"clientDataJSON": {
"type": "string",
"description": "base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server."
}
}
},
"getClientExtensionResults": {
"type": "object",
"description": "content with FIDO2 extions",
"properties": {}
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"user": {
"id": "abcdef0123456789",
"name": "[email protected]"
},
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"name": {
"type": "string",
"description": "User account. Usually email format."
}
}
},
"key_info": {
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}
}
}Step 2PUT/{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.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
MFA - include Passkey ¶
Identity Verify with FIDO2 Device ¶
POST /abcdefgh0123456789/api/v1/webauthn/verification
Requests
Headers
Content-Type: applicatoin/jsonBody
{
"uId": "[email protected]",
"params": {
"userVerification": "required"
}
}Schema
{
"type": "object",
"properties": {
"uId": {
"type": "string",
"description": "User account. Usually email format."
},
"params": {
"type": "object",
"properties": {
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
}
}
}Responses
Headers
Content-Type: applicaton/jsonBody
{
"code": 0,
"fido_auth_request": {
"challenge": "abcdef0123456789",
"timeout": 12345,
"rpId": "www.example.com",
"allowCredentials": [{"type": "public-key", "id": "abcdef0123456789"},...],
"userVerification": "required",
"extensions": {}
}
}Schema
{
"type": "object",
"description": {
"code": {
"type": "number",
"description": "API result status code"
},
"fido_auth_request": {
"type": "object",
"properties": {
"challenge": {
"type": "string",
"description": "base64-url format display byte array source."
},
"timeout": {
"type": "number",
"description": "This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete."
},
"rpId": {
"type": "string",
"description": "website hostname"
},
"allowCredentials": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"id": {
"type": "string",
"description": "Credential ID in UTF8 string type"
}
}
},...
]
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
},
"extensions": {
"type": "object",
"properties": {},
"description": "This member contains additional parameters requesting additional processing by the client and authenticator."
}
}
}
}
}Step 1POST/{API_ACCESSPOINT}/api/v1/webauthn/verification
Get FIDO2 authentication request from AuthFi server for specific user.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Identity Verify Authentication response to server ¶
PUT /abcdefgh0123456789/api/v1/webauthn/verification
Requests
Headers
Content-Type: applicatoin/jsonBody
{
"fido_auth_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}Schema
{
"type": "object",
"properties": {
"fido_auth_response": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator."
},
"rawId": {
"type": "string",
"description": "base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server."
},
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"response": {
"type": "object",
"properties": {
"authenticatorData": {
"type": "string",
"description": "base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server."
},
"signature": {
"type": "string",
"description": "base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server."
},
"userHandle": {
"type": "string",
"description": "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"
},
"clientDataJSON": {
"type": "string",
"description": "base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server."
}
}
},
"getClientExtensionResults": {
"type": "object",
"description": "content with FIDO2 extions",
"properties": {}
}
}
}
}
}Responses
Headers
Content-Type: applicaton/jsonBody
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"uid": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"key_info": {
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}
}
}Step 2PUT/{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.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Management ¶
Get register user list ¶
GET /abcdefgh0123456789/api/v1/users?page=1&size=20
Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"total": 1,
"users": [{
"id": "abcdef0123456789",
"name": "[email protected]",
"state": "activate",
"create_time": 12345,
"update_time": 12345
},...]
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"total": {
"type": "number",
"description": "Number of register users."
},
"users": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "User ID in AuthFi server"
},
"name": {
"type": "string",
"description": "User name"
},
"state": {
"type": "string",
"description": "User status of permission use FIDO2 authentication. One of 'activate', 'suspend'"
},
"create_time": {
"type": "number",
"description": "UTC time when user information registered on AuthFi"
},
"update_time": {
"type": "number",
"description": "UTC time when user information updated on AuthFi"
}
}
}
]
}
}
}GET/{API_ACCESSPOINT}/api/v1/users{?page,size}
Get registered user information from AuthFi.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- page
number(optional) Example: 1Page index of query informations
- size
number(optional) Example: 20Records max size of response array, range from 20 to 100, default is 20.
Change target user state ¶
PUT /abcdefgh0123456789/api/v1/users/abcdefgh0123456789
Requests
Headers
Content-Type: applicaton/jsonBody
{
"state": "activate"
}Schema
{
"type": "object",
"properties": {
"status": {
"type": "string",
"describtion": "New status for user. One of 'activate', 'suspend'"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"user": {
"id": "abcdef0123456789",
"name": "[email protected]",
"state": "activate",
"create_time": 12345,
"update_time": 12345
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "User ID in AuthFi server"
},
"name": {
"type": "string",
"description": "User name"
},
"state": {
"type": "string",
"description": "User status of permission use FIDO2 authentication. One of 'activate', 'suspend'"
},
"create_time": {
"type": "number",
"description": "UTC time when user information registered on AuthFi"
},
"update_time": {
"type": "number",
"description": "UTC time when user information updated on AuthFi"
}
}
}
}
}PUT/{API_ACCESSPOINT}/api/v1/users/{userId}
Change user status with activate and suspend to allowed or to blocked user to use FIDO2 authentication.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- userId
string(required) Example: abcdefgh0123456789The user ID stored in AuthFi server
Delete target user ¶
DELETE /abcdefgh0123456789/api/v1/users/abcdefgh0123456789
Responses
Headers
Content-Type: applicaton/jsonBody
{
"code": 0,
"deleteUser": {
"id": "abcdef0123456789",
"name": "[email protected]"
},
"deleteUserRegisterKeys": 1
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"deleteUser": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "User ID in AuthFi server"
},
"name": {
"type": "string",
"description": "User name"
}
}
}
"deleteUserRegisterKeys": {
"type": "number",
"description": "Number of delete user register keys was deleted"
}
}
}DELETE/{API_ACCESSPOINT}/api/v1/users/{userId}
To delete a registered user and all user registered keys.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- userId
string(required) Example: abcdefgh0123456789The user ID stored in AuthFi server
Get a user registered key information ¶
GET /abcdefgh0123456789/api/v1/users/abcdefgh0123456789/keys
Responses
Headers
Content-Type: applicatoin/jsonBody
{
"code": 0,
"total": 1,
"keys": [
{
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
},...
]
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"total": {
"type": "number",
"description": "key count, max size 10"
},
"keys": {
"type": "array",
"items": [{
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}]
}
}
}GET/{API_ACCESSPOINT}/api/v1/users/{userId}/keys
Get all user registered security keys information.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- userId
string(required) Example: abcdefgh0123456789The user ID from AuthFi server
Set a friendly name to register security key ¶
PUT /abcdefgh0123456789/api/v1/users/abcdefgh0123456789/keys/abcdefgh0123456789
Requests
Headers
Content-Type: applicaton/jsonBody
{
"name": "New key name"
}Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"describtion": for human friendly reading to specify securty key
}
}
}Responses
Headers
Content-Type: applicaton/jsonBody
{
"code": 0,
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "New key name",
"create_time": 12345,
"update_time": 12345
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"key_info": {
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}
}
}PUT/{API_ACCESSPOINT}/api/v1/users/{userId}/keys/{id}
Set a easily readable name to identify different key.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- userId
string(required) Example: abcdefgh0123456789The user ID from AuthFi server
- id
string(required) Example: abcdefgh0123456789The Credential ID from AuthFi server
Delete a user registered security key ¶
DELETE /abcdefgh0123456789/api/v1/users/abcdefgh0123456789/keys/abcdefgh0123456789
Responses
Headers
Content-Type: applicaton/jsonBody
{
"code": 0,
"deleteKeys": 1
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"deleteKeys": {
"type": "number",
"description": "delete register keys count"
}
}
}DELETE/{API_ACCESSPOINT}/api/v1/users/{userId}/keys/{id}
Delete a registered security key
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- userId
string(required) Example: abcdefgh0123456789The user ID from AuthFi server
- id
string(required) Example: abcdefgh0123456789The Credential ID from AuthFi server
Non-Passkey Mobile App API ¶
Get a QRCode for register with authenticator app ¶
POST /abcdefgh0123456789/api/v1/mobile/registration/qrcode
Requests
Headers
Content-Type: application/jsonBody
{
"params": {
"user": "[email protected]",
"path": "/PATH_NAME/HTML_FILE_NAME_or_API_NAME_for_getting_html_texts"
}
}Schema
{
"type": "object",
"properties": {
"params": {
"type": "object",
"properties": {
"user": {
"type": "string",
"describtion": "The user email to register with authenticator app"
},
"path": {
"type": "string",
"describtion": "The path to access mobile register page, ex: /app/register.html"
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"token": "abcdef0123456789",
"image": "abcdef0123456789",
"expire_at": 12345
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"token": {
"type": "string",
"descriptioin": "QRCode ID"
},
"image": {
"type": "string",
"descriptioin": "base64 form string to present QRCode in PNG image file"
},
"expire_at": {
"type": "number",
"descriptioin": "UTC time value in future that QRCode will expire"
}
}
}POST/{API_ACCESSPOINT}/api/v1/mobile/registration/qrcode
Get a QRCode to display on PC browser side for registration with authenticator app (ex. AT.AuthFi Authenticator)
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Poll authenticator app register result ¶
GET /abcdefgh0123456789/api/v1/mobile/registration/result?token=abcdefgh0123456789
Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"app_result": 1
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"app_result": {
"type": "number",
"description": "authenticator app registration result. 0: authenticator register success. 1: wait for authenticator app to finish register. 2: authenticator register fail."
}
}
}GET/{API_ACCESSPOINT}/api/v1/mobile/registration/result{?token}
Get authenticator app register result on PC browser side.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- token
string(required) Example: abcdefgh0123456789The QRCode token from AuthFi server.
Register with authenticator app ¶
POST /abcdefgh0123456789/api/v1/mobile/registration
Requests
Headers
Content-Type: application/jsonBody
{
"params": {
"token": "abcdef0123456789",
"user": {
"name": "[email protected]",
"displayName": "Foo Bar"
},
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
},
"attestation": "direct"
}
}Schema
{
"type": "object",
"properties": {
"params": {
"type": "object",
"properties": {
"token": {
"type": "string",
"descriptioin": "QRCode ID"
},
"user": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "User account."
},
"displayName": {
"type": "string",
"description": "User name."
}
}
},
"authenticatorSelection": {
"type": "object",
"properties": {
"authenticatorAttachment": {
"type": "string",
"description": "Option describe authenticator type. One of 'cross-platform', 'platform'. 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Kye. 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID"
},
"requireResidentKey": {
"type": "boolean",
"description": "When the requireResidentKey attribute is true, the authenticator must create a client side resident private key."
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
},
"attestation": {
"type": "string",
"description": "Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation. One of 'none', 'indirect', 'direct'. '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."
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"fido_register_request": {
"rp": {
"id": "www.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"
}
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"fido_register_request": {
"type": "object",
"properties": {
"rp": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "website hostname"
},
"name": {
"type": "string",
"description": "website name"
}
}
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"name": {
"type": "string",
"description": "User account. Usually email format."
},
"displayName": {
"type": "string",
"description": "User name."
}
}
},
"challenge": {
"type": "string",
"description": "base64-url format display byte array source."
},
"pubKeyCredParams": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"alg": {
"type": "number",
"description": "COSE Algorithms registry"
}
}
},...
]
},
"timeout": {
"type": "number",
"description": "This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete."
},
"excludeCredentials": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"id": {
"type": "string",
"description": "Credential ID in UTF8 string type"
}
}
},...
]
},
"extensions": {
"type": "object",
"properties": {},
"description": "This member contains additional parameters requesting additional processing by the client and authenticator."
},
"authenticatorSelection": {
"type": "object",
"properties": {
"authenticatorAttachment": {
"type": "string",
"description": "Option describe authenticator type. One of 'cross-platform', 'platform'. 'cross-platform': For authenticator able to work on all supoort platform. Such as USB Security Kye. 'platform': For authenticator is bundle with devices. Such as Windows Hello and iOS touchID"
},
"requireResidentKey": {
"type": "boolean",
"description": "When the requireResidentKey attribute is true, the authenticator must create a client side resident private key."
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
},
"attestation": {
"type": "string",
"description": "Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation. One of 'none', 'indirect', 'direct'. '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."
}
}
}
}
}Register Step 1POST/{API_ACCESSPOINT}/api/v1/mobile/registration
Send authenticator register parameters to AuthFi server to obtain FIDO2 Security Key register request. And to use authenticator app as Security Key. Please use following value
authenticatorSelection: {
"authenticatorAttachment": "platform",
"requireResidentKey": true,
"userVerification": "preferred"
}attestation: "direct"
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Register with authenticator app ¶
PUT /abcdefgh0123456789/api/v1/mobile/registration
Requests
Headers
Content-Type: application/jsonBody
{
"token": "abcdef0123456789",
"fido_register_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"attestationObject": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789",
"getAuthenticatorData": {},
"getPublicKey": {},
"getPublicKeyAlgorithm": {},
"getTransports": {}
},
"getClientExtensionResults": {}
}
}Schema
{
"type": "object",
"properties": {
"token": {
"type": "string",
"descriptioin": "QRCode ID"
},
"fido_register_response": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator."
},
"rawId": {
"type": "string",
"description": "base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server."
},
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"response": {
"type": "object",
"properties": {
"attestationObject": {
"type": "string",
"description": "base64-url format string of attestationObject byte array. Response from authenticator. Need convert by client web or server."
},
"clientDataJSON": {
"type": "string",
"description": "base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server."
},
"getAuthenticatorData": {
"type": "object",
"description": "authenticator data object response by authenticator",
"properties": {}
},
"getPublicKey": {
"type": "object",
"description": "publickey object response by authenticator",
"properties": {}
},
"getPublicKeyAlgorithm": {
"type": "object",
"description": "publickey algorithm object response by authenticator",
"properties": {}
},
"getTransports": {
"type": "object",
"description": "transports object response by authenticator",
"properties": {}
}
}
},
"getClientExtensionResults": {
"type": "object",
"description": "content with FIDO2 extions",
"properties": {}
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "abcdef0123456789",
"counter": 1,
"name": "",
"create_time": 12345,
"update_time": 12345
}
Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"uid": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"key_info": {
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}
}
}Register Step 2PUT/{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.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Get just registered user name ¶
GET /abcdefgh0123456789/api/v1/mobile/registration/user?token=abcdefgh0123456789
Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"account": "[email protected]"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"account": {
"type": "string",
"description": "User account. Usually email format."
}
}
}GET/{API_ACCESSPOINT}/api/v1/mobile/registration/user{?token}
For authenticator app to get register user name for display on main menu.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- token
string(required) Example: abcdefgh0123456789The QRCode token from AuthFi server.
Get a QRCode for verify with authenticator app ¶
POST /abcdefgh0123456789/api/v1/mobile/verification/qrcode
Requests
Headers
Content-Type: application/jsonBody
{
"params": {
"path": "/PATH_NAME/HTML_FILE_NAME_or_API_NAME_for_getting_html_texts"
}
}Schema
{
"type": "object",
"properties": {
"params": {
"type": "object",
"properties": {
"path": {
"type": "string",
"describtion": "The path to access mobile verify page, ex: /app/verify.html"
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"token": "abcdef0123456789",
"image": "abcdef0123456789",
"expire_at": 12345
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"token": {
"type": "string",
"descriptioin": "QRCode ID"
},
"image": {
"type": "string",
"descriptioin": "base64 form string to present QRCode in PNG image file"
},
"expire_at": {
"type": "number",
"descriptioin": "UTC time value in future that QRCode will expire"
}
}
}POST/{API_ACCESSPOINT}/api/v1/mobile/verification/qrcode
On PC browser to get a QRCode for authenticator app to scan for FIDO authentication.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Poll authenticator app verify result ¶
GET /abcdefgh0123456789/api/v1/mobile/verification/result?token=abcdefgh0123456789
Responses
Headers
Content-Type: application/jsonBody
{
code: 0,
app_result: 1
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"app_result": {
"type": "number",
"description": "authenticator app registration result. 0: authenticator register success. 1: wait for authenticator app to finish register. 2: authenticator register fail."
}
}
}GET/{API_ACCESSPOINT}/api/v1/mobile/verification/result{?token}
On PC browser to get authenticator app verify result.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
- token
string(required) Example: abcdefgh0123456789The QRCode token from AuthFi server.
Verify with authenticator app ¶
POST /abcdefgh0123456789/api/v1/mobile/verification
Requests
Headers
Content-Type: application/jsonBody
{
"uId": "[email protected]",
"token": "abcdef0123456789",
"params": {
"userVerification": "preferred"
}
}Schema
{
"type": "object",
"properties": {
"uId": {
"type": "string",
"description": "User account. Usually email format."
},
"token": {
"type": "string",
"descriptioin": "QRCode ID"
},
"params": {
"type": "object",
"properties": {
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"fido_auth_request": {
"challenge": "abcdef0123456789",
"timeout": 12345,
"rpId": "www.example.com",
"allowCredentials": [{"type": "public-key", "id": "abcdef0123456789"},...],
"userVerification": "preferred",
"extensions": {}
}
}Schema
{
"type": "object",
"description": {
"code": {
"type": "number",
"description": "API result status code"
},
"fido_auth_request": {
"type": "object",
"properties": {
"challenge": {
"type": "string",
"description": "base64-url format display byte array source."
},
"timeout": {
"type": "number",
"description": "This member specifies a time, in milliseconds, that the caller is willing to wait for the call to complete."
},
"rpId": {
"type": "string",
"description": "website hostname"
},
"allowCredentials": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"id": {
"type": "string",
"description": "Credential ID in UTF8 string type"
}
}
},...
]
},
"userVerification": {
"type": "string",
"description": "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. One of 'required', 'preferred' and 'discouraged'. '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)."
},
"extensions": {
"type": "object",
"properties": {},
"description": "This member contains additional parameters requesting additional processing by the client and authenticator."
}
}
}
}
}Verify Step 1POST/{API_ACCESSPOINT}/api/v1/mobile/verification
For authenticator app to get FIDO2 authentication request from AuthFi server for specific user.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Verify with authenticator app ¶
PUT /abcdefgh0123456789/api/v1/mobile/verification
Requests
Headers
Content-Type: application/jsonBody
{
"token": "abcdef0123456789",
"fido_auth_response": {
"id": "abcdef0123456789",
"rawId": "abcdef0123456789",
"type": "public-key",
"response": {
"authenticatorData": "abcdef0123456789",
"signature": "abcdef0123456789",
"userHandle": "abcdef0123456789",
"clientDataJSON": "abcdef0123456789"
},
"getClientExtensionResults": {}
}
}Schema
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "QRCode ID"
},
"fido_auth_response": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "base64-url format string of credential ID byte array. This should equal to base64-url encode rawId content. Response from authenticator."
},
"rawId": {
"type": "string",
"description": "base64-url format string of credential ID byte array. Response from authenticator. Need convert by client web or server."
},
"type": {
"type": "string",
"description": "Defines the valid credential types. Static content 'public-key'"
},
"response": {
"type": "object",
"properties": {
"authenticatorData": {
"type": "string",
"description": "base64-url format string of authenticatorData byte array. Response from authenticator. Need convert by client web or server."
},
"signature": {
"type": "string",
"description": "base64-url format string of signature byte array. Response from authenticator. Need convert by client web or server."
},
"userHandle": {
"type": "string",
"description": "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"
},
"clientDataJSON": {
"type": "string",
"description": "base64-url format string of clientDataJSON byte array. Response from authenticator. Need convert by client web or server."
}
}
},
"getClientExtensionResults": {
"type": "object",
"description": "content with FIDO2 extions",
"properties": {}
}
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"code": 0,
"uid": "abcdef0123456789",
"key_info": {
"credential_id": "VGhpcyBpcyBhIGV4YW1wbGUgSUQ",
"counter": 1,
"name": "KeyA",
"create_time": 12345,
"update_time": 12345
}
Schema
{
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "API result status code"
},
"uid": {
"type": "string",
"description": "base64-url format user ID byte array source."
},
"key_info": {
"type": "object",
"properties": {
"credential_id": {
"type": "string",
"description": "human readable ID string to identify credential in security key."
},
"counter": {
"type": "number",
"description": "counter for FIDO2 authentication."
},
"name": {
"type": "string",
"description": "Human easily readble name to identify Security Key"
},
"create_time": {
"type": "number",
"description": "UTC time when the credential was create."
},
"update_time": {
"type": "number",
"description": "UTC time when the information in credential was update."
}
}
}
}
}Verify Step 2PUT/{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.
URI Parameters
- API_ACCESSPOINT
string(required) Example: abcdefgh0123456789The API access point you receive when you apply a new RelyingParty.
Error Codes ¶
Following list all the error codes will return in response and what it preset.
1000
Which means you are access API without correct informations. Such as not carry API Key,
wrong API Key or access point, or RP/User information is not able to be found on AuthFi (were deleted).
Please check with your informations.
1001
Which means you are block by accessing APIs. Response with this error when RP reach Trailed expire date or suspend by AuthFi for reasons. Please contect with AuthFi client services.
1002
It means parameters send from RP server are not acceptable.
-
page index too large
-
record size of each page not between 20 to 100
-
user ID is wrong, AuthFi not able to find the user by user ID.
-
credential ID from Security Key is wrong, AuthFi not able to find the key by credential ID.
-
not sent user id when doing identity verification
2000
User try to do FIDO2 Security Key registration or authentication by Security Key, but RP set user as suspend.
3000
When RP is in trail state or just apply for activate, there is max users limitaion. API will return this code when users count is reached limitation and new user is trying to register Security Key.
3001
Every user can register as much as 10 keys in single RP. This code will be returned when user is trying to register more than 10 keys.
3100
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The fido_register_response object send by RP server got wrong format, missing items or parsing error will receive this code.
3200
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content is not suit to FIDO2 specification.
3300
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content in U2F format is not suit to FIDO2 specification.
3400
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content in Packed format is not suit to FIDO2 specification.
3500
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content in TPM format is not suit to FIDO2 specification.
3600
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content in Android SafetyNet format is not suit to FIDO2 specification.
3700
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content in Android Key format is not suit to FIDO2 specification.
3800
Server will response this error code when doing PUT /api/v1/webauthn/registration or PUT /api/v1/mobile/registration.
The attestation object content in Apple format is not suit to FIDO2 specification.
3900
Server will response this error code when doing PUT /api/v1/webauthn/login, /api/v1/webauthn/verification or PUT /api/v1/mobile/verification or PUT /api/v1/mobile/verification.
The fido_login_response/fido_auth_response object send by RP server got wrong format, missing items or parsing error will receive this code.
4000
Server will response this error code when fido_xxx_response contain clientDataJSON which got wrong format, missing items or parsing error
4100
Server will response this error code when fido_register_response contain response.attestationObject.authData which got wrong format, missing items or parsing error. And when fido_login_response/fido_auth_rersponse contain response.authenticatorData which got wrong format, missing items or parsing error.
4200
Server will response this error code when fido_xxx_response contains wrong flag informations.
5000
Server will response this error code when FIDO register/login/verify request were handle over 30 seconds on AuthFi.
51xx
Server will response these error codes when mobile API request were found some thing wrong.
5100
QRCode token was not found on AuthFi.
5101
QRCode was expired.
5102
QRCode was used.
5103
Not able to find register user name with QRCode token.
5104
User register name on authenticator app is not same as create QRCode user information.
7000
Server will response this error code when some data store with wrong value not expected.
8000
Server will response this error code when there are some unexpect errors happend.
Generated by aglio on 12 May 2023