AuthFi APIs

API Endpoint

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_code key in the JSON response.

  • The request method (verb) determines the nature of action you intend to perform. A request made using the GET method implies that you want to fetch something from AuthFi, and POST implies you want to save something new to AuthFi.

  • The API calls will respond with appropriate HTTP status codes for all requests. A 2XX indicates all went well, while 4XX or 5XX response 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 github to know how to implement AuthFi API in your service.

FIDO2 Security Key register

Register a FIDO2 Security Key

POST /abcdefgh0123456789/api/v1/webauthn/registration
Requestssample
Headers
Content-Type: application/json
Body
{
    "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', 'prefered' 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."
                }
            }
        }
    }
}
Responses200
Headers
Content-Type: application/json
Body
{
    "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', 'prefered' 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 1
POST/{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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The 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
Requestssample
Headers
Content-Type: application/json
Body
{
  "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": {}
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/json
Body
{
  "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 2
PUT/{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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.


FIDO2 First Factor Login

Login with a FIDO2 Security Key

POST /abcdefgh0123456789/api/v1/webauthn/login
Requestssample
Headers
Content-Type: applicaton/json
Body
{
  "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', 'prefered' 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)."
        }
      }
    }
  }
}
Responses200
Headers
Content-Type: applicaton/json
Body
{
  "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', 'prefered' 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 1
POST/{API_ACCESSPOINT}/api/v1/webauthn/login

URI Parameters
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.


Login Authentication response to server

PUT /abcdefgh0123456789/api/v1/webauthn/login
Requestssample
Headers
Content-Type: application/json
Body
{
  "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."
            },
            "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": {}
        }
      }
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "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 2
PUT/{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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.


FIDO2 Second Factor Identity Verify

Identity Verify with FIDO2 Device

POST /abcdefgh0123456789/api/v1/webauthn/verification
Requestssample
Headers
Content-Type: applicatoin/json
Body
{
  "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', 'prefered' 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)."
        }
      }
    }
  }
}
Responses200
Headers
Content-Type: applicaton/json
Body
{
    "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', 'prefered' 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 1
POST/{API_ACCESSPOINT}/api/v1/webauthn/verification

Get FIDO2 authentication request from AuthFi server for specific user.

URI Parameters
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.


Identity Verify Authentication response to server

PUT /abcdefgh0123456789/api/v1/webauthn/verification
Requestssample
Headers
Content-Type: applicatoin/json
Body
{
  "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."
            },
            "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": {}
        }
      }
    }
  }
}
Responses200
Headers
Content-Type: applicaton/json
Body
{
    "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 2
PUT/{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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The 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
Responses200
Headers
Content-Type: application/json
Body
{
    "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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.

page
number (optional) Example: 1

Page index of query informations

size
number (optional) Example: 20

Records max size of response array, range from 20 to 100, default is 20.


Change target user state

PUT /abcdefgh0123456789/api/v1/users/abcdefgh0123456789
Requestssample
Headers
Content-Type: applicaton/json
Body
{
    status: "activate"
}
Schema
{
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "describtion": "New status for user. One of 'activate', 'suspend'"
        }
    }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.

userId
string (required) Example: abcdefgh0123456789

The user ID stored in AuthFi server


Delete target user

DELETE /abcdefgh0123456789/api/v1/users/abcdefgh0123456789
Responses200
Headers
Content-Type: applicaton/json
Body
{
  "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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.

userId
string (required) Example: abcdefgh0123456789

The user ID stored in AuthFi server


Get a user registered key information

GET /abcdefgh0123456789/api/v1/users/abcdefgh0123456789/keys
Responses200
Headers
Content-Type: applicatoin/json
Body
{
    "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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.

userId
string (required) Example: abcdefgh0123456789

The user ID from AuthFi server


Set a friendly name to register security key

PUT /abcdefgh0123456789/api/v1/users/abcdefgh0123456789/keys/abcdefgh0123456789
Requestssample
Headers
Content-Type: applicaton/json
Body
{
    name: "New key name"
}
Schema
{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "describtion": for human friendly reading to specify securty key
        }
    }
}
Responses200
Headers
Content-Type: applicaton/json
Body
{
  "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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.

userId
string (required) Example: abcdefgh0123456789

The user ID from AuthFi server

id
string (required) Example: abcdefgh0123456789

The Credential ID from AuthFi server


Delete a user registered security key

DELETE /abcdefgh0123456789/api/v1/users/abcdefgh0123456789/keys/abcdefgh0123456789
Responses200
Headers
Content-Type: applicaton/json
Body
{
  "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
HideShow
API_ACCESSPOINT
string (required) Example: abcdefgh0123456789

The API access point you receive when you apply a new RelyingParty.

userId
string (required) Example: abcdefgh0123456789

The user ID from AuthFi server

id
string (required) Example: abcdefgh0123456789

The Credential ID from AuthFi server


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.
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.
The attestation object content is not suit to FIDO2 specification.

3300

Server will response this error code when doing PUT /api/v1/webauthn/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.
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.
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.
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.
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.
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 or /api/v1/webauthn/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.

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 30 Nov 2021