Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

  • Core Products
  • Add-Ons
  • Extensions Marketplace
Android
iOS
Web

Generate token using REST API

Interactive Whiteboard uses different types of tokens for user authentication. For details, see Interactive Whiteboard Token overview.

This article introduces how to call the Interactive Whiteboard RESTful API to generate tokens.

Generate an SDK Token (POST)​

Call this API to generate an SDK Token.

Prototype​

  • Method: POST
  • Access point: https://api.netless.link/v5/tokens/teams

Request header​

Pass in the following parameters in the request header:

ParameterData typeRequired/OptionalDescription
regionstringRequiredSpecifies a data center to process the request:
  • us-sv: Silicon Valley, US, which provides services to North America and South America.
  • sg: Singapore, which provides services to Singapore, East Asia, and Southeast Asia.
  • in-mum: Mumbai, India, which provides services to India.
  • eu: Frankfurt, Europe, which provides services to Europe.
  • cn-hz: Hangzhou, China, which provides services to the areas not covered by other data centers.

    • Request body​

    ParameterData typeRequired/OptionalDescription
    accessKeystringRequiredThe Access Key (AK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
    secretAccessKeystringRequiredThe Secret Key (SK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
    lifespanintegerRequiredThe token validity period (milliseconds). If you set it to 0, the token is permanently valid.
    rolestringRequiredThe token role:
  • admin
  • writer
  • reader
    • See Token Overview.

    Request example​


    _11
    POST /v5/tokens/teams
    _11
    Host: api.netless.link
    _11
    region: us-sv
    _11
    Content-Type: application/json
    _11
    _11
    {
    _11
    "accessKey": "BUxxxxxxrc",
    _11
    "secretAccessKey": "CxxxxxxxauY3",
    _11
    "lifespan": 3600000,
    _11
    "role": "admin"
    _11
    }

    HTTP response​

    For details about all possible response status codes, see the status code table.

    If the status code is 201, the request is successful. The response returns the generated sdk token.

    The following is a response example for a successful request:


    _4
    "status": 201,
    _4
    "body":
    _4
    { "NETLESSSDK_YWs9xxxxxxY2E2OQ"
    _4
    }

    If the status code is not 201, the request fails. The response body includes a message field that describes the reason for the failure.

    Generate a Room Token (POST)​

    Call this API to generate a Room Token.

    Prototype​

    • Method: POST
    • Access point: https://api.netless.link/v5/tokens/rooms/{uuid}

    Request header​

    Pass in the following parameters in the request header:

    ParameterData typeRequired/OptionalDescription
    tokenstringRequiredThe SDK Token, which can be obtained through one of the following methods:
  • Get a test-purpose SDK token from Agora Console. See Get security credentials for your whiteboard project.
  • Call the RESTful API. See Generate an SDK token.
  • Write code on your app server. See Generate a token from your app server.
    • regionstringRequiredSpecifies a data center to process the request:
  • us-sv: Silicon Valley, US, which provides services to North America and South America.
  • sg: Singapore, which provides services to Singapore, East Asia, and Southeast Asia.
  • in-mum: Mumbai, India, which provides services to India.
  • eu: Frankfurt, Europe, which provides services to Europe.
  • cn-hz: Hangzhou, China, which provides services to the areas not covered by other data centers.

    • Request path​

    The following parameters are required in the URL:

    ParameterData typeRequired/OptionalDescription
    uuidstringRequiredThe Room UUID, which is the unique identifier of a room. You can get it by calling the RESTful API to create a room or the RESTful API to get room information.

    Request body​

    ParameterData typeRequired/OptionalDescription
    lifespanintegerRequiredThe token validity period (milliseconds). If you set it to 0, the token is permanently valid.
    rolestringRequiredThe token role:
  • admin
  • writer
  • reader
    • See Token Overview.

    Request example​


    _10
    POST /v5/tokens/rooms/a7exxxxxca69
    _10
    Host: api.netless.link
    _10
    token: NETLESSSDK_YWs9Qxxxxxx2MjRi
    _10
    region: us-sv
    _10
    Content-Type: application/json
    _10
    _10
    {
    _10
    "lifespan": 3600000,
    _10
    "role": "admin"
    _10
    }

    HTTP response​

    For details about all possible response status codes, see the status code table.

    If the status code is 201, the request is successful. The response returns the generated room token.

    The following is a response example for a successful request:


    _4
    "status": 201,
    _4
    "body":
    _4
    { "NETLESSROOM_YWs9xxxxxxY2E2OQ"
    _4
    }

    If the status code is not 201, the request fails. The response body includes a message field that describes the reason for the failure.

    Generate a Task Token (POST)​

    Call this API to generate a Task Token.

    Prototype​

    • Method: POST
    • Access point: https://api.netless.link/v5/tokens/tasks/{uuid}

    Request header​

    Pass in the following parameters in the request header:

    ParameterData typeRequired/OptionalDescription
    tokenstringRequiredThe SDK Token, which can be obtained through one of the following methods:
  • Get a test-purpose SDK Token from Agora Console. See Get security credentials for your whiteboard project.
  • Call the RESTful API. See Generate an SDK token.
  • Write code on your app server. See Generate a token from your app server.
    • regionstringRequiredSpecifies a data center to process the request:
  • us-sv: Silicon Valley, US, which provides services to North America and South America.
  • sg: Singapore, which provides services to Singapore, East Asia, and Southeast Asia.
  • in-mum: Mumbai, India, which provides services to India.
  • eu: Frankfurt, Europe, which provides services to Europe.
  • cn-hz: Hangzhou, China, which provides services to the areas not covered by other data centers.

    • Request path​

    The following parameters are required in the URL:

    ParameterData typeRequired/OptionalDescription
    uuidstringRequiredThe task UUID, which is the unique identifier of a file-conversion task. You can get it by calling the RESTful API to start a file-conversion task or the RESTful API to query the task progress.

    Request body​

    ParameterData typeRequired/OptionalDescription
    akstringOptionalThe Access Key (AK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
    lifespanintegerRequiredThe token validity period (milliseconds). If you set it to 0, the token is permanently valid.
    rolestringRequiredThe token role:
  • admin
  • writer
  • reader
    • See Token Overview.

    Request example​


    _10
    POST /v5/tokens/tasks/a7e0xxxxxxxca69
    _10
    Host: api.netless.link
    _10
    token: NETLESSSDK_YWs9QlxxxxxxM2MjRi
    _10
    region: us-sv
    _10
    Content-Type: application/json
    _10
    _10
    {
    _10
    "lifespan": 600,
    _10
    "role": "admin"
    _10
    }

    HTTP response​

    For details about all possible response status codes, see the status code table.

    If the status code is 201, the request is successful. The response returns the generated task token.

    The following is a response example for a successful request:


    _4
    "status": 201,
    _4
    "body":
    _4
    { "NETLESSTASK_YWxxxxxxM2ViMQ"
    _4
    }

    If the status code is not 201, the request fails. The response body includes a message field that describes the reason for the failure.

    vundefined