createAccessToken

First introduced in version: 3.00.6.3

Syntax

createAccessToken(userId, [expire], [description])

Details

Creates a persistent access token that the specified user can use to log into the DolphinDB server.

Non-admin users can create tokens only for themselves; administrators can create tokens for other users.

Note:

  • The complete token is returned only once when it is created, and cannot be queried or recovered later. Store it securely.

  • Changing a user's password does not automatically revoke their access tokens; deleting a user removes all their access tokens.

  • The configuration parameter maxAccessTokensPerUser limits the number of valid tokens a user can hold simultaneously.

  • Access tokens created with createAccessToken cannot be backed up with backupSettings or restored with restoreSettings.

  • Once access tokens have been created using createAccessToken, the following restrictions apply when downgrading the Server:

    • If an access token has ever been created for admin, downgrading to a version earlier than 3.00.6.3 is not supported.

    • If access tokens have been created only for users other than admin, you must delete all users who have ever had an access token before downgrading to a version earlier than 3.00.6.3.

Arguments

userId is a STRING scalar specifying the user name.

expire (optional) is a DATETIME scalar specifying the expiration time. By default, no expiration time is set.

description (optional) is a STRING scalar specifying a description. The default value is empty.

Returns

A STRING->ANY dictionary containing the following keys:

  • tokenId: The token identifier.

  • token: The complete token.

Examples

Create a token with an expiration time.

The token identifier and complete token vary each time. The output below illustrates the dictionary structure.

// Get the current user name
accountName = getCurrentSessionAndUser()[1]

// Create an access token
accessCredential = createAccessToken(userId=accountName, expire=2030.12.31T23:59:59, description="MCP client")
accessCredential
/* output:
tokenId->2aff381ac39b
token-><access token returned at creation>
*/

Related functions: revokeAccessToken, listAccessTokens, authenticateByTicket