Generating an Access Token
Last updated: 2026-01-07 14:42:34
Description
This API is used to generate the Access Token for calling Smart Media Hosting (SMH) services. Calling this API requires the use of a Media Library Key, so it must be called in the backend to ensure key security.
Note:
This API is used to obtain the Access Token for subsequent calls to other APIs for media hosting. Calling this API requires the use of a LibrarySecret, so it must be called in the backend to ensure key security.
The UserId in the request parameters is an optional user identifier for the business system. The media hosting backend does not interpret the specific meaning of this parameter. It is solely used to distinguish the user to whom the Access Token belongs and to record the operator of relevant actions. It is recommended that developers set UserId to the business-specific user identifier (such as Mini Program openid or the business's own user ID) for Access Tokens used by frontend users to operate media hosting. For Access Tokens used by backend services to directly operate media hosting, set UserId to null.
The ClientId in the request parameters is an optional business-specific client identifier. It is used to distinguish different endpoints when the same user logs in from multiple devices. This can be employed to proactively clear valid access tokens on other clients. For example, when a user logs in through multiple mobile clients, mobile WeChat Mini Programs, and PC WeChat Mini Programs, the business backend can record the number of clients the user has logged into. It also allows users to proactively clear login states on specified clients. In such cases, relevant APIs can be called to clear access tokens on designated clients.
When an access token with administrator permissions is applied for and the UserId is empty, a UserId can be carried simultaneously as a temporary identity in subsequent requests using the access token. In this case, the requester will be considered as that specified user identity.
There is no limit on the number of access tokens that can be applied for by the same user identity, to meet the need for simultaneous login on multiple devices.
When an access token is used to call an API, it will be automatically renewed, with the renewed validity period being the duration specified by the Period parameter.
When the business backend receives a request from the frontend to obtain a request token, it should first verify the user identity from the frontend, and then set the Grant parameter in the request token request based on the user's permissions within the business.
Request
Request Example
GET /api/v1/token?library_id=`{LibraryId}`&library_secret=`{LibrarySecret}`&space_id=`{SpaceId}`&user_id=`{UserId}`&client_id=`{ClientId}`&session_id=`{SessionId}`&period=`{Period}`&grant=`{Grant}`
or
POST /api/v1/token?library_id=`{LibraryId}`&library_secret=`{LibrarySecret}`&space_id=`{SpaceId}`&user_id=`{UserId}`&client_id=`{ClientId}`&period=`{Period}`&grant=`{Grant}`
Note:
The content within curly braces represents variable parameters when requests are made. In actual usage, do not include the curly braces. For example:
/api/v1/token?library_id=smhxxx&library_secret=1234abcd&space_id=spacexxx&user_id=ABCD1234&grant=upload_file,create_directory, hereinafter the same.Request Parameter
Request parameters. | Description | Type | Required or Not |
LibraryId | Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library | String | Yes |
LibrarySecret | Media Library Key, obtained after creating a media library in the Media Hosting console. See Create Media Library | String | Yes |
SpaceId | Space ID. You can specify multiple Space IDs simultaneously, separated by commas. | String | If the media library is in single-tenant mode, no need to specify this parameter If the media library is in multi-tenant mode, no need to specify this parameter when operating tenant space. For other operations, this parameter is selectable if admin permission is granted, otherwise must specify this parameter. |
UserId | User identity recognition, managed by the backend | String | No |
ClientId | Client identification, managed by the backend | String | No |
SessionId | SessionId, managed by the backend | String | No |
Period | Token valid duration and auto-renewal duration after each use, optional parameter, in seconds. Valid values: positive integer. Input other value will use default value 86400 (24 hours). Input less than 300 will automatically use minimum value 300 (5 minutes). Input more than 315360000 will automatically use maximum value 315360000 (10 years). | String | No |
Grant | The granted permission. If left empty, only read permission is granted. You can specify this parameter to add multiple permissions on the basis of read-only, and use commas (,) to separate them, such as: create_directory,upload_file | String | No |
The following are the permission items supported by the Grant parameter:
Permission Item | Description |
admin | administrator privileges, grant all privileges |
create_space | have permission to create tenant space |
delete_space | have permission to delete tenant space |
space_admin | tenant space administrator privileges, have all privileges except tenant space operations |
create_directory | have permission to create directories or albums |
delete_directory | have permission to delete directories or albums (recycle bin not enabled)/move directories or albums to recycle bin (recycle bin enabled) |
delete_directory_permanent | have permission to permanently delete directories or albums (recycle bin enabled) |
move_directory | have permission to rename or move directories or albums |
copy_directory | have permission to copy directories or albums |
upload_file | have permission to upload files, but not allowed to overwrite existing files |
upload_file_force | have permission to upload files and overwrite existing files |
begin_upload | have permission to start file upload, but not allowed to overwrite existing files |
begin_upload_force | have permission to start file upload and overwrite existing files |
confirm_upload | Have permission to complete file upload; separate the start uploading and upload completion permissions, mainly used for the separation of frontend and backend business permissions, so that upload completion must transit the business backend; if both start uploading and upload completion permissions are required, simply assign upload_file or upload_file_force. |
create_symlink | have permission to create symbolic links, but not allowed to overwrite existing files or symbolic links |
create_symlink_force | have permission to create symbolic links and overwrite existing files or symbolic links |
delete_file | have permission to delete files (recycle bin not enabled)/move files to recycle bin (recycle bin enabled) |
delete_file_permanent | have permission to permanently delete files (recycle bin enabled) |
move_file | have permission to rename or move files, but not allowed to overwrite existing files |
move_file_force | have permission to rename or move files and overwrite existing files |
copy_file | have permission to copy files, but not allowed to overwrite existing files |
copy_file_force | have permission to copy files and overwrite existing files |
delete_recycled | have permission to delete items in the recycle bin |
restore_recycled | have permission to restore items in the recycle bin |
set_history_latest | have permission to set a certain earlier version to the latest version |
delete_history | have permission to delete earlier versions |
Request Body
Empty or application/json, access token extended attribute can be specified (POST method only)
{"attachInfo": {"operatorPhoneNumber": "18628769878"}}
Request body field description:
Node Name (Keyword) | Description | Type | Optional or Not |
attachInfo | Trigger information, JSON Object, to record logs | Json | No |
Response
Response code
Successfully generated, return HTTP 200 OK.
Response Body
{"accessToken": "acctk01f7af4f07me88u2svxwp9tszuekqlprquuejxxxxxx","expiresIn": 86400}
Response body field description:
Node Name (Keyword) | Description | Type |
accessToken | specific value of the access token | String |
expiresIn | Valid duration of the access token, in seconds | Int |
Error Codes
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback