The Provisioning, Usage, and Billing APIs have a request parameter named signature
. This parameter is an encrypted string shared between vendors and Agora. It allows vendors to verify HTTP requests sent by Agora.
This page explains how to generate a signature.
The signature combines the source string (SourceString
) and your secret key (apiSecret&
) using an encryption algorithm, as follows:
GET and PUT methods:
signature = URLEncode(Base64( HMAC-SHA1( apiSecret&, SourceString) ), "UTF-8")
POST methods:
signature = Base64( HMAC-SHA1( apiSecret&, SourceString) )
After receiving the request, you need to apply the encryption algorithm to generate a signature on your own. If the generated signature is the same as the one you receive, you can verify that the request is sent by Agora.
Take the Usage API for example, Agora sends the following request to query usage information:
https://[host]/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pzD5XinRSlmA64tZx81fL92YcBsJK0gd&signature={signature}
For this example, the parameters used in the encryption algorithm are as follows:
Parameter | Value |
---|---|
SourceString |
GET&%2Fusage&apiKey%3DpzD5XinRSlmA64tZx81fL92YcBsJK0gd%26fromTs%3D1619913600%26pageNum%3D1%26toTs%3D1619917200 |
apiSecret |
U1SXE6k57vxVRjTomgquwC2F3tH8ziOB (This is for demonstration only. Your actual apiSecret should be different.) |
signature |
SFVnCVlRbrZcjMPGTWVxAE4QWZ8%3D |
This section shows how to generate the signature step-by-step.
To construct SourceString
, follow these steps:
Get the type of the HTTP request and add an "&":
GET&
In the request URL, leave only the path after [host]
and before ?
(if any), URL-encode the resulting string (that is, /usage
), and add an "&". The source string now looks like:
GET&%2Fusage&
Sequence the query parameters in the request URL except signature
(that is, fromTs
, toTs
, and apiKey
) in alphabetical ascending order in the form of key=value
, and combine them using "&":
apiKey=pzD5XinRSlmA64tZx81fL92YcBsJK0gd&fromTs=1619913600&pageNum=1&toTs=1619917200
URL-encode the string above and add it to the source string:
GET&%2Fusage&apiKey%3DpzD5XinRSlmA64tZx81fL92YcBsJK0gd%26fromTs%3D1619913600%26pageNum%3D1%26toTs%3D1619917200
To construct the secret key, add an “&” to the end of your apiSecret string.
For example, if the apiSecret you provide when applying to become a vendor is U1SXE6k57vxVRjTomgquwC2F3tH8ziOB, the secret key should be U1SXE6k57vxVRjTomgquwC2F3tH8ziOB&
.
The encryption algorithm for GET methods is as follows:
signature = URLEncode(Base64( HMAC-SHA1( apiSecret&, SourceString) ), "UTF-8")
Using the SourceString
and apiSecret&
from previous steps, you get this signature:
SFVnCVlRbrZcjMPGTWVxAE4QWZ8%3D
Take the Provisioning API for example, Agora sends the following request body:
{
"projectId": "430892",
"apiKey": "pzD5XinRSlmA64tZx81fL92YcBsJK0gd",
"signature": "To be generated"
}
And the request URL is:
https://[host]/customers/123456/projects/new
For this example, the parameters used in the encryption algorithm are as follows:
Parameter | Value |
---|---|
SourceString |
POST&%2Fcustomers%2F123456%2Fprojects%2Fnew&apiKey%3DpzD5XinRSlmA64tZx81fL92YcBsJK0gd%26projectId%3D430892 |
apiSecret |
U1SXE6k57vxVRjTomgquwC2F3tH8ziOB (This is for demonstration only. Your actual apiSecret should be different.) |
signature |
QRJDBm3gGmlFb5ZF9XBqm7u4EkI= |
This section shows how to generate the signature step-by-step.
To construct SourceString
, follow these steps:
Get the type of the HTTP request and add an "&":
POST&
In the request URL, leave only the path after [host]
and before ?
(if any), URL-encode the resulting string (that is, /usage
), and add an "&". The source string now looks like:
POST&%2Fcustomers%2F123456%2Fprojects%2Fnew&
Sequence the query parameters in the request body except signature
(that is, projectId
and apiKey
) in alphabetical ascending order in the form of key=value
, and combine them using "&":
apiKey=pzD5XinRSlmA64tZx81fL92YcBsJK0gd&projectId=430892
URL-encode the string above and add it to the source string:
POST&%2Fcustomers%2F123456%2Fprojects%2Fnew&apiKey%3DpzD5XinRSlmA64tZx81fL92YcBsJK0gd%26projectId%3D430892
To construct the secret key, add an “&” to the end of your apiSecret string.
For example, if the apiSecret you provide when applying to become a vendor is U1SXE6k57vxVRjTomgquwC2F3tH8ziOB, the secret key should be U1SXE6k57vxVRjTomgquwC2F3tH8ziOB&
.
The encryption algorithm for POST methods is as follows:
signature = Base64( HMAC-SHA1( apiSecret&, SourceString) )
Using the SourceString
and apiSecret&
from previous steps, you get this signature:
QRJDBm3gGmlFb5ZF9XBqm7u4EkI=