Authentication
Wonder API uses AppID and RSA Public Key to authenticate requests. You can generate AppID Pair in Wonder Dashboard.
Need to use AppID and RSA Public Key to generate credential and signature, for more details please refer the following.
When call every OpenAPI, please use the generated credential and signature script to be the prefix operation and generated credential and signature in the header
- Requests will be rejected if the RequestTime in the Credential leave the Wonder server for over than 30 minutes.
- Credential format: $APPID/$REQUEST_DATE/Wonder-RSA-SHA256.
Generate RSA key pair
openSSL is the most popular open source project for cryptography. Follow the openssl command below to generate an rsa key pair.
# generate a private key with 2048 bit key size
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
# generate the public key, your should copy-paste the full content when you try to create a appid on wonder-dashboard
openssl rsa -pubout -in private_key.pem -out public_key.pem
The Public Key needs to be uploaded in the Wonder Dashboard to get the Appid, if the private key is lost, you have to regenerate the RSA Key pair and regenerate the Appid.
Please be careful with your private key, no one will have any reason to get your private key.
Credential and signature algorithm
Common HTTP Request Header
| Header Name | Example | Comment |
|---|---|---|
| Credential | d900da8b-6e16-4a85-8a66-05d29ac53f24/20240501120123/Wonder-RSA-SHA256 | - |
| Signature | lM42cgyuLS98Dieydc8K2OD3KwYkOXibpV9pFvr/R0i/830M/FPKUKba v2UBBN3M3EdPk/PpvKQlvBNT+NbEg20C KuiDTZWDc3r7KiA1pdZsui/57XCVhC2s01W8jEM+G5lS362+p8+E0K6 UKQDrJMyVpbDT31XSkSJIxae+uDi2nJr4DnIkemeU2LlNDRPPGe9NeX7z3B3N3LwIi QgKMyauPqAjro0UrZykQM9pv4UySRSU2cT8EcjQmyKxbzy uR2A47PyeodJvotlIthdfCHIxG52D06tpRJlRVbUdvxSg14bFiPbr3F wCvruZlbR15gOanJCqE4wp4fC8qEXXsg== | - |
| Nonce | 0000000000000000 | randomly 16 bytes |
| Content-Type | application/json | - |
| X-Request-ID | d900da8b-6e16-4a85-8a66-05d29ac53f24 | unique HTTP request tracking id,please make sure each request is unique. |
1. Generate credential
Once you have the appid, generate the credential using the following rules:
CREDENTIAL="$APPID/$REQUEST_TIME/Wonder-RSA-SHA256"
$REQUEST_TIME is UTC time in yyyymmddHHMMSS format:
- yyyy: 4 digits years
- mm: 2 digits months
- dd: 2 digits days
- HH 2 digits hours
- MM 2 digits minutes
- SS 2 digits seconds
When send HTTP request, you need to add header Credential: $CREDENTIAL
Notice: Needs to be generated in UTC time zone, not local time
2. Generate nonce
Nonce is a random 16 bytes alphanumerics.
When send HTTP request, you need to add header Nonce: $Nonce
3. Generate signature
#The Appid generated on wonder dashboard
APPID="${YOUR_APPID}"
# Please refer to generate RSA key pair
SIGNATURE_RSA_PRIVATE_KEY="${YOUR_SIGNATURE_RSA_PRIVATE_KEY}"
REQUEST_TIME="20231201154523" #Format:YYYYMMDDhhmmss, please make sure it's UTC time
#random 16-bit alphanumerics
NONCE="<Randomly Nonce>"
HTTP_URI="$API_URI_PATH" #The full url Path
HTTP_METHOD="$API_HTTP_METHOD" #HTTP Method, GET / POST
BODY = "$API_REQUEST_BODY" #The raw request body
CREDENTIAL="$APPID/$REQUEST_TIME/Wonder-RSA-SHA256"
PRE_SIGNATURE_STRING=HTTP_METHOD + "\n" + HTTP_URI
# If it is a Get request or the request body is empty, then this step is not needed
IF BODY AND LENGTH(BODY) > 0 THEN
PRE_SIGNATURE_STRING = PRE_SIGNATURE_STRING + "\n" + BODY
ENDIF
SIGNATURE = HMAC_SHA256($NONCE,$REQUEST_TIME)
SIGNATURE = HMAC_SHA256($SIGNATURE,"Wonder-RSA-SHA256")
SIGNATURE = HMAC_SHA256($SIGNATURE,$PRE_SIGNATURE_STRING)
HEXED_HASH = HEX($SIGNATURE)
FINAL_SIGNATURE = BASE64_ENCODE(RSA_SHA256_PKCS1v15($SIGNATURE_RSA_PRIVATE_KEY,$HEXED_HASH))
When send HTTP request, you need to add header Signature: $FINAL_SIGNATURE
Verify webhook signature
When you generate the AppID Pair, you can download the Webhook Signature Public Key, which is an RSA key pair managed by Wonder Gateway. Each Webhook will be signed with the RSA private key, and you can verify the legitimacy of the Webhook with the Webhook Signature Public Key you downloaded.
BODY = http_request.request_body
HTTP_METHOD = http_request.method
HTTP_URI = http_request.uri
CREDENTIAL = http_request.headers['Credential']
PARSED_CREDENTIAL = PARSE_CREDENTIAL(CREDENTIAL)
NONCE = http_request.headers['Nonce']
RECEIVED_SIGNATURE = http_request.headers['Signature']
APPID = PARSED_CREDENTIAL['appid']
REQUEST_TIME = PARSED_CREDENTIAL['request_time']
ALGORITHM = PARSED_CREDENTIAL['algorithm']
WEBHOOK_PUBLIC_KEY = "<You will receive the public key when you created appid.>"
PRE_SIGNATURE_STRING = HTTP_METHOD + "\n" + HTTP_URI
# If it is a Get request or the request body is empty, then this step is not needed
IF BODY AND LENGTH(BODY) > 0 THEN
PRE_SIGNATURE_STRING = PRE_SIGNATURE_STRING + "\n" + BODY
ENDIF
SIGNATURE = HMAC_SHA256($NONCE,$REQUEST_TIME)
SIGNATURE = HMAC_SHA256($SIGNATURE,$ALGORITHM)
SIGNATURE = HMAC_SHA256($SIGNATURE,$PRE_SIGNATURE_STRING)
HEXED_HASH = HEX($SIGNATURE)
RSA_SHA256_PKCS1v15_VERIFY($WEBHOOK_PUBLIC_KEY,$HEXED_HASH,$RECEIVED_SIGNATURE)
Source Codes
Please refer to Signature Examples
Online Signature Debug Tool
Through the Wonder Gateway Online Signature Debug Tool you can quickly online debugging signature and webhook verification of each detailed step, we recommend that you through this tool for development debugging.