Implement licensing

Agora grants a device-specific license to bill for its services, with each device having its own unique license. During the license validity period, the standard minutes included with the license cover the duration-based charges for audio and video calls. Any usage beyond the included quota is converted into standard minutes and charged at the applicable standard-minute rate. Typically, device manufacturers predict the sales volume and usage of their devices, buy and activate licenses from Agora, and then embed the license into each device in the form of a single code.

Understand the tech

The following figure shows the overall process of using an IoT SDK device license:

Obtain and use a device license

Follow the steps below to add a license to your IoT SDK devices.

Apply for a license

Agora provides each developer with 10 free trial licenses, valid for 6 months, each including a quota of 150 standard minutes per month. To apply for additional or commercial licenses, contact support@agora.io and provide the following information:

Note the following when you fill out the license application:

• License type: Choose a trial license or a commercial license. Agora recommends that you use a trial license during integration testing, and switch to a commercial license before the official launch. For further details, see Trial license and commercial license.
• Stock keeping unit (SKU): Specify the capability set of the license, including the following parameters:
  • Product: Media Stream Acceleration (RTSA) / IoT SDK.
  • License capabilities: Audio, video, or both audio and video.
  • Upper limit of license minutes: Whether to limit the duration for using the license, which is accurate to minutes.
  • License usage period: Whether to limit the period for using the license, which is accurate to minutes.
• Validity period: The validity period of the license starts on the day of activation.
  • Trial license: Specify the period in days. Minimum is 3 days.
  • Commercial license: Specify the period in years. Minimum is 1 year.

Obtain pre-authorization

To reduce the risk of license theft, Agora requires pre-authorization before you can activate a license. Send your project's App ID and the device's licenseKey to support@agora.io to add the device to an activation whitelist. The activation API only succeeds when you pass a whitelisted licenseKey. Pre-authorizing a device consumes one license from your purchased quantity.

Activate a license

After receiving pre-authorization, refer to the information in this section to activate the license.

Request

• Method: POST
• Access point: https://api.agora.io/global/dabiz/license/v2/active

Request parameters

The activation request requires the following query parameters:

Request example

curl --location --request POST 'https://api.agora.io/global/dabiz/license/v2/active?pid=02F5xxxxxxxxxxxxxxxxxxxxxxxxEC30&licenseKey=111&appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e' \
--header 'Authorization: <http_basic_auth>'

Response parameters If the status code is 200, the request is successful, and the response body contains the following parameters:

Response example

The following is a response example for a successful activation request:

{
   "code": 200,
   "data": {
      "pid": "E4D6xxxxxxxxxxxxxxxxxxxxxxxx7E79",
      "license": "1D65xxxxxxxxxxxxxxxxxxxxxxxx6016",
      "licenseKey": "1234xxxxxxxxxxx1234",
      "expireTime": 1700000000,
      "activationTime": 1699000000,
      "skuView": {
         "product": 1
      }
   }
}

If the request fails, the status code is not 200. Follow the returned status code and the message field in the response body to troubleshoot errors.

Use the license

After successfully activating a license, you write the license to the device and use it in the SDK. Take the following steps to use the license:

1. Receive an activated license from the server.

2. Write the license to the device. Ensure that the license written to each device is correct and unique. There are two common methods to write the license information to your device:

   • Write the license to a file on the device, and have your program read it.
   • The manufacturer burns the license into the device during production, and the device reads it directly.

3. Device reads license:

   • If the device successfully reads the license, proceed to the next step.
   • If the device fails to read the license, troubleshoot the problem and write the license again.

4. In the IoT SDK, call agora_rtc_init and pass the license in the license_value parameter of rtc_service_option_t.

5. The IoT SDK automatically verifies the license when a user joins a channel.

   • If the license verification is successful, the user can use the functions of the SDK.

   • If the license verification fails, the SDK kicks the user out of the channel and triggers the on_license_validation_failure callback with an error code, so your app can report and handle the failure explicitly:

     static void __on_license_validation_failure(connection_id_t conn_id, int reason) {
         printf("License verification failed, reason: %d\n", reason);
     }

     Assign the handler in your event handler setup:

     event_handler->on_license_validation_failure = __on_license_validation_failure;

Check license usage

Check your license usage in Agora Console.

Renew a license

Agora recommends renewing a license at least 30 days before it expires, to avoid a service interruption. You can only renew a license once its remaining validity period is shorter than the validity period of the renewal you request.

Request

• Method: POST
• Access point: https://api.agora.io/global/dabiz/license/v2/renew

Request parameters

Request example

curl --location --request POST 'https://api.agora.io/global/dabiz/license/v2/renew?appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e&renewId=4750xxxxxxxxxxxxxxxxxxxxxxxx6270&license=85B3xxxxxxxxxxxxxxxxxxxxxxxx656F' \
--header 'Authorization: <http_basic_auth>'

Response parameters

If the status code is 200, the request is successful, and the response body contains the following parameters:

Response example

{
  "code": 200,
  "message": "license renewed successfully",
  "data": {
    "licenseKey": "1234xxxxxxxxxxx1234",
    "license": "85B3xxxxxxxxxxxxxxxxxxxxxxxx656F",
    "renewTimes": 1,
    "lastRenewTime": 1700644272,
    "activationTime": 1699000000,
    "expireTime": 1705913065
  }
}

Check for expiring licenses

Query which of your licenses are expiring soon so you can renew them in time.

Request

• Method: GET
• Access point: https://api.agora.io/global/dabiz/license/v3/projects/{appId}/pids/{pid}/expiringLicenses

Path parameters

Query parameters

Request example

curl --location --request GET 'https://api.agora.io/global/dabiz/license/v3/projects/{appId}/pids/{pid}/expiringLicenses?expiringDay=90&size=10&page=1' \
--header 'Authorization: <http_basic_auth>'

Response parameters

If the status code is 200, the request is successful, and the response body contains the following parameters:

Response example

{
  "code": 200,
  "data": {
    "count": 1,
    "list": [
      {
        "license": "698AxxxxxxxxxxxxxxxxxxxxxxxxEDDB0",
        "licenseKey": "1234xxxxxxxxxxx1234",
        "activeTime": "2024-12-02T08:15:39Z",
        "expireTime": "2024-12-05T08:15:39Z"
      }
    ]
  }
}

Check renewal orders

Request

• Method: GET
• Access point: https://api.agora.io/global/dabiz/license/v3/projects/{appId}/renewals

Path parameters

Request example

curl --location --request GET 'https://api.agora.io/global/dabiz/license/v3/projects/{appId}/renewals' \
--header 'Authorization: <http_basic_auth>'

Response parameters

If the status code is 200, the request is successful, and the response body contains a list of renewal orders. Each order includes renewId, pid, the renewal type, the renewal duration, totalCount, allocateCount, and createTime.

Reference

The content in this section completes the information on this page, or points you to documentation that explains other aspects of this product.

Difference between licenseValue and licenseKey

licenseValue is the ID of each license. You need this value to renew a license. You receive the activated licenseValue in the response when you call the activation API.

licenseKey is the unique identifier of the device. For example, the SN number, or the Mac address. The string length must be less than 64 bytes. When a user calls the activation API to activate a license for a device, the user consumes the license which is passed in the licenseKey parameter. Users can perform pre-authorization operations, so that only the licenseKey in the whitelist can successfully activate the license.

Trial and commercial license

To facilitate development and testing, Agora offers the following types of licenses:

• Trial license: For integration-testing and product debugging. Every developer gets 10 free trial licenses, valid for 6 months, each including a quota of 150 standard minutes per month. Minimum validity period for additional trial licenses you request is 3 days.
• Commercial license: For the launch stage of the product. Minimum validity period is 1 year.

Best practice is to use a trial license before the product is officially launched. To switch to a commercial license, follow these steps:

1. Contact support@agora.io to apply for a commercial license. After successfully applying for a license, you can check the PID of the license in the License Usage page of the Agora Console.
2. Call the activation API to activate a new license and pass in the PID of the new license and the licenseKey which is consistent with the old license.
3. Write the new license to the device and read it.
4. Call the initialization method of the SDK with the new license.

API reference

• agora_rtc_init()