All Products
Search

This Product

    Elastic Desktop Service:GetLoginToken

    Document Center

    Elastic Desktop Service:GetLoginToken

    Last Updated:Oct 08, 2026

    Retrieves a logon credential.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    No authorization for this operation. If you encounter issues with this operation, contact technical support.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The region ID. Call DescribeRegions to query the list of regions supported by Alibaba Cloud Workspace.

    cn-hangzhou
    ClientId

    string

    Yes

    The unique ID generated by the client.

    f4a0dc8e-1702-4728-9a60-95b27a35****
    DirectoryId

    string

    No

    The office network ID. This parameter has the same meaning as OfficeSiteId. Stop using DirectoryId and use OfficeSiteId instead. You can specify only one of DirectoryId and OfficeSiteId. Do not specify both.

    cn-hangzhou+dir-885351****
    OfficeSiteId

    string

    No

    The office network ID.

    cn-hangzhou+dir-885351****
    SessionId

    string

    No

    The session ID for logon.

    • If no virtual MFA device is bound or client secondary authentication is not enabled, you do not need to specify SessionId.

    • If a virtual MFA device is bound or client secondary authentication is enabled, you must specify SessionId in the authentication stages after ADPassword. You can obtain SessionId from the response of the convenience account verification request (that is, when GetLoginToken is in the ADPassword stage).

    cd45e873-650d-4d70-acb9-f996187a****
    CurrentStage

    string

    No

    The current logon authentication stage. The stages are as follows:

    • ADPassword: Verifies user credentials. Specify this value when using password-based authentication for a convenience account or an AD account.

    • MFABind: Binds a virtual MFA device.

    • MFAVerify: Verifies the security code generated by the virtual MFA device.

    • TokenVerify: Performs client secondary authentication.

    • ChangePassword: Changes the user password.

    • KeepAliveVerify: When the KeepAliveToken is valid, exchanges it for a LoginToken.

    ADPassword
    EndUserId

    string

    No

    The username of the convenience user or AD user. This parameter is required when CurrentStage is set to ADPassword.

    alice
    Password

    string

    No

    The password of the convenience user or AD user. This parameter is required when CurrentStage is set to ADPassword.

    Password1234
    OldPassword

    string

    No

    The old password. This parameter is required when CurrentStage is set to ChangePassword.

    OldPassword
    NewPassword

    string

    No

    The new password. This parameter is required when CurrentStage is set to ChangePassword.

    NewPassword
    AuthenticationCode

    string

    No

    The security code generated by the virtual MFA device. This parameter is required when CurrentStage is set to MFAVerify.

    47****
    ClientOS

    string

    No

    The operating system of the device running the client.

    Windows_NT 10.0.18363 x64
    ClientVersion

    string

    No

    The client version. If you are using the Alibaba Cloud Workspace client, you can view this parameter in the About dialog box on the client logon page.

    2.1.0-R-20210731.151756
    TokenCode

    string

    No

    The secondary authentication verification code. If client secondary authentication is enabled in the Alibaba Cloud Workspace console and the current logon user is identified as a risk, this code is sent to the end user's mailbox. This parameter is required when CurrentStage is set to TokenVerify.

    63****
    KeepAlive

    boolean

    No

    Specifies whether to keep the user logged on. Valid values:

    Valid values:

    • null :

      Do not keep the user logged on. [Default value]

    • true :

      Keep the user logged on.

    • false :

      Do not keep the user logged on.

    false
    KeepAliveToken

    string

    No

    The token used to keep the user logged on. After a successful logon with the keep-logged-on option enabled, the operation returns a KeepAliveToken. While the KeepAliveToken is valid, you can call GetLoginToken with CurrentStage set to KeepAliveVerify to exchange it for a logon credential (LoginToken). This parameter is required when CurrentStage is set to KeepAliveVerify.

    hide
    Uuid

    string

    No

    The unique identifier of the client. If you are using the Alibaba Cloud Workspace client, you can view this parameter in the About dialog box on the client logon page.

    C78CA9E99315687575DD2844C1F3****
    ClientType

    string

    No

    The type of the Alibaba Cloud Workspace software client. Valid values:

    Valid values:

    • HTML5 :

      Web client.

    • WINDOWS :

      Windows client.

    • MACOS :

      macOS client.

    • IOS :

      iOS client.

    • ANDROID :

      Android client.

    WINDOWS
    AvailableFeatures

    object

    No

    The features supported by the client.

    string

    No

    The features supported by the client.

    ClientName

    string

    No

    The client name.

    Response elements

    Element

    Type

    Description

    Example

    object

    The returned information.

    Email

    string

    The user's email address. Returned with the LoginToken after logon.

    • For a convenience user, the email address set when the convenience user was created is returned.

    • For an AD user, the value is returned in the following format: username@AD domain name.

    alice
    Secret

    string

    The key used when attaching a virtual MFA device. Used in the MFABind stage.

    Note

    For details about each authentication stage, see the metric description of the CurrentStage request parameter for this operation.

    5OCLLKKOJU5HPBX66H3QCTWYI7MH****
    RequestId

    string

    The request ID.

    1CBAFFAB-B697-4049-A9B1-67E1FC5F****
    EndUserId

    string

    The convenience account username or AD username.

    alice
    LoginToken

    string

    The logon credential.

    v18101ac6a9e69c66b04a163031680463660b4b216cd758f34b60b9ad6a7c7f7334b83dd8f75eef4209c68f9f1080b****
    NextStage

    string

    The expected next stage. For example, if the administrator has enabled MFA authentication in the Alibaba Cloud Workspace console, after the username and password authentication passes (that is, after the ADPassword stage), this parameter returns MFAVerify, indicating that MFA authentication is required.

    Note

    For details about each authentication stage, see the metric description of the CurrentStage request parameter for this operation.

    MFAVerify
    QrCodePng

    string

    The QR code of the key used when attaching a virtual MFA device. Encoded using Base64 encoding. This value can be empty. Used in the MFABind stage.

    Note

    For details about each authentication stage, see the metric description of the CurrentStage request parameter for this operation.

    5OCLLKKOJU5HPBX66H3QCTWY******
    Label

    string

    The convenience user attributes. Returns an empty value for AD users.

    test:wuying
    SessionId

    string

    The session ID. Returned only on the first invoke of GetLoginToken within the same session. If multiple authentication stages are required, subsequent stages must include this parameter.

    Note

    For details about each authentication stage, see the metric description of the CurrentStage request parameter for this operation.

    d6ec166d-ab93-4286-bf7f-a18bb929****
    Phone

    string

    The phone number of the convenience user. Returns an empty value for AD users.

    1381111****
    TenantId

    integer

    The Alibaba Cloud account ID. Used for hardware terminal identification.

    166353906220****
    KeepAliveToken

    string

    The token used to keep the user logged on. After a successful logon with the keep-logged-on option enabled, the operation returns a KeepAliveToken. If the keep-logged-on option is not enabled, an empty value is returned.

    006YwvYMsesWWsDBZnVB+Wq9AvJDVIqOY3YCktvtb7+KxMb3ClnNlV8+l/knhZYrXUmeP06IzkjF+IgcZ3vZKOyMprDyFHjCy1r27FRE/U7+geWCl8iQ+yF8GaCRHfJEkC2+ROs93HkT4tfHxyY1J8W7O7ZQGUC/cdCvm+cCP6FIy73IUuPuVR6PcKYXIpEZPW
    Industry

    string
    Note

    This is an internal field and is not available for external use.

    edu
    Props

    object
    Note

    This is an internal field and is not available for external use.

    string
    Note

    This is an internal field and is not available for external use.

    {'dingUserName': u'\u674e\u66fc', 'role': 'student'}
    WindowDisplayMode

    string
    Note

    This is an internal field and is not available for external use.

    mode
    RiskVerifyInfo

    object

    The information related to logon risk identification.

    Email

    string

    The email address used for identity verification when a risk is triggered.

    user@example.com
    LastLockDuration

    integer

    The duration for which the account is locked.

    1713749778
    Locked

    string

    Indicates whether the account is locked. Valid values:

    Valid values:

    • true :

      Yes.

    • false :

      No.

    true
    Phone

    string

    The phone number used for identity verification when a risk is triggered.

    1381111****
    Reason

    string
    Note

    This is an internal field and is not available for external use.

    null
    PasswordStrategy

    object
    Note

    This is an internal field and is not available for external use.

    TenantPasswordLength

    string
    Note

    This is an internal field and is not available for external use.

    null
    TenantAlternativeChars

    array
    Note

    This is an internal field and is not available for external use.

    string
    Note

    This is an internal field and is not available for external use.

    null
    NickName

    string

    The nickname of the user.

    user-001
    WyId

    string

    OfficeSiteId

    string

    The office network ID.

    cn-hangzhou+dir-885351****
    OfficeSiteName

    string

    The office network name.

    test

    Examples

    Success response

    JSON format

    {
  "Email": "alice",
  "Secret": "5OCLLKKOJU5HPBX66H3QCTWYI7MH****",
  "RequestId": "1CBAFFAB-B697-4049-A9B1-67E1FC5F****",
  "EndUserId": "alice",
  "LoginToken": "v18101ac6a9e69c66b04a163031680463660b4b216cd758f34b60b9ad6a7c7f7334b83dd8f75eef4209c68f9f1080b****",
  "NextStage": "MFAVerify",
  "QrCodePng": "5OCLLKKOJU5HPBX66H3QCTWY******",
  "Label": "test:wuying",
  "SessionId": "d6ec166d-ab93-4286-bf7f-a18bb929****",
  "Phone": "1381111****",
  "TenantId": 0,
  "KeepAliveToken": "006YwvYMsesWWsDBZnVB+Wq9AvJDVIqOY3YCktvtb7+KxMb3ClnNlV8+l/knhZYrXUmeP06IzkjF+IgcZ3vZKOyMprDyFHjCy1r27FRE/U7+geWCl8iQ+yF8GaCRHfJEkC2+ROs93HkT4tfHxyY1J8W7O7ZQGUC/cdCvm+cCP6FIy73IUuPuVR6PcKYXIpEZPW",
  "Industry": "edu",
  "Props": {
    "key": "{'dingUserName': u'\\u674e\\u66fc', 'role': 'student'}"
  },
  "WindowDisplayMode": "mode",
  "RiskVerifyInfo": {
    "Email": "user@example.com",
    "LastLockDuration": 1713749778,
    "Locked": "true",
    "Phone": "1381111****"
  },
  "Reason": "null",
  "PasswordStrategy": {
    "TenantPasswordLength": "null",
    "TenantAlternativeChars": [
      "null"
    ]
  },
  "NickName": "user-001",
  "WyId": "",
  "OfficeSiteId": "cn-hangzhou+dir-885351****",
  "OfficeSiteName": "test"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.