本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护

Documentation





All

Console 官网 Community Technical support





Generate a Token Using RESTful API

Last updated 2022/06/10 07:10:04

Agora 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:

Parameter	Data type	Required/Optional	Description
`region`	string	Required	Specifies 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. `gb-lon`: London, England, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Request body

Parameter	Data type	Required/Optional	Description
`accessKey`	string	Required	The Access Key (AK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
`secretAccessKey`	string	Required	The Secret Key (SK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
`lifespan`	integer	Required	The token validity period (milliseconds). If you set it to `0`, the token is permanently valid.
`role`	string	Required	The token role: `admin` `writer` `reader` See Token Overview.

Request example

POST /v5/tokens/teams
Host: api.netless.link
region: us-sv
Content-Type: application/json

{
    "accessKey": "BUxxxxxxrc",
    "secretAccessKey": "CxxxxxxxauY3",
    "lifespan": 3600000,
    "role": "admin"
}

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:

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

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:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	The 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.
`region`	string	Required	Specifies 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. `gb-lon`: London, England, 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:

Parameter	Data type	Required/Optional	Description
`uuid`	string	Required	The 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

Parameter	Data type	Required/Optional	Description
`ak`	string	Optional	The Access Key (AK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
`lifespan`	integer	Required	The token validity period (milliseconds). If you set it to `0`, the token is permanently valid.
`role`	string	Required	The token role: `admin` `writer` `reader` See Token Overview.

Request example

POST /v5/tokens/rooms/a7exxxxxca69
Host: api.netless.link
token: NETLESSSDK_YWs9Qxxxxxx2MjRi
region: us-sv
Content-Type: application/json

{
    "lifespan": 3600000,
    "role": "admin"
}

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:

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

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:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	The 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.
`region`	string	Required	Specifies 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. `gb-lon`: London, England, 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:

Parameter	Data type	Required/Optional	Description
`uuid`	string	Required	The 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

Parameter	Data type	Required/Optional	Description
`ak`	string	Optional	The Access Key (AK), which can be obtained in Agora Console. See Get security credentials for your whiteboard project.
`lifespan`	integer	Required	The token validity period (milliseconds). If you set it to `0`, the token is permanently valid.
`role`	string	Required	The token role: `admin` `writer` `reader` See Token Overview.

Request example

POST /v5/tokens/tasks/a7e0xxxxxxxca69
Host: api.netless.link
token: NETLESSSDK_YWs9QlxxxxxxM2MjRi
region: us-sv
Content-Type: application/json

{
    "lifespan": 600,
    "role": "admin"
}

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:

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

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

Is this page helpful?

Yes