WebAPI Common Information

WebAPI Common Information

• All APIs are accessed via HTTPS communication.
• All APIs are called by specifying the API name as a path under https://fss-app.yubion.com/api/.
• All HTTP methods are requested with POST.
• All APIs except getNonce require the setting of common HTTP headers and the sending of authentication information in the headers, as described later.
• Sending of API parameters and reception of request results are all done in JSON format.
• Some requests that need to be processed consecutively (FIDO authentication registration/authentication processing) require cookie retention.

Common HTTP Headers for API Requests

API Authentication Methods

Three types of API authentication methods are provided.

Signature Authentication (Nonce Signature Authentication / Date Signature Authentication)

The secret key is the private key information for signature creation (ECDSA P-256, private key information in pkcs8 format Base64Url encoded). Using that private key, a signature is performed on the following concatenated byte string.

[ Data to be signed for each authentication format ] || [ SHA-256 hash value of the request body ]

• “Data to be signed for each authentication format” is a byte string of the following UTF-8 string.

  • Nonce signature authentication The Nonce string obtained in the getNonce request. This string must be specified in “X-Fss-Auth-Nonce” of the request header. API authentication will fail in the following cases.
    • When a Nonce string not issued by the FSS server is used
    • When a Nonce string that has already been used is used
    • When a certain period of time has passed since the Nonce string was issued
  • Date signature authentication A string representing the current date and time in ISO8601 format. This string must be specified in “X-Fss-Auth-Request-Time” of the request header. If there is a difference of 30 seconds or more from the FSS server time, API authentication will fail.

• “SHA-256 hash value of the request body” is a byte string of the SHA-256 hash of the request body. It is necessary to specify a Base64Url encoded string of the hash value in “X-Fss-Auth-Body-Hash” of the request header.

• The signature result is output in 64-byte Raw Format (P1363 Format) with R and S concatenated, and a Base64Url encoded string of it is specified in “X-Fss-Auth-Signature” of the request header.

Access Key Authentication

• Specify the issued secret key as it is in “X-Fss-Auth-Access-Key” of the request header.

API Response Basic Format

The basic format of all API responses is explained.

{
	appStatus : "OK",
	data : {
		...
	},
	message : "...",
	appSubStatus : {
		...
	},
}

API Execution Result Information (ApplicationResultStatus)

ApplicationResultStatus takes the following values.

Detailed Error Information during FIDO Authentication Registration/Authentication Processing

When an error occurs in FIDO authentication registration/authentication processing (registerCredential/xxx, authenticate/xxx), the errorCode property may be set in appSubStatus.

{
	appStatus : "PARAMETER_ERROR",
	message : "...",
	appSubStatus : {
		errorCode : "",
		...
	},
}

This errorCode takes the following values.