Log in

Applies to: API integrators with third-party API access.

First integration? Follow the Quick start for account prerequisites, cURL requests and the device-to-order workflow.

Use Content-Type: application/json and optionally X-Locale: en. No token is required for this endpoint. See common headers and error handling.

Brief Description

• User login endpoint to retrieve the Access Token and user identity information.
• The login response identifies the selected Group in groupId. Check it before making business queries.
• switchableGroups lists the Groups available to the account.
• Subsequent authenticated endpoints require the third-api-token header (with the value set to accessToken).

Request URL

• https://{GATEWAY_HOST}/polarstar-auth/auth/third-api/token

Request Method

• POST

Parameters

Request Body:

Parameter Name	Required	Type	Description
username	Yes	string	Login username
password	Yes	string	Login password

Response Example

{
  "code": 200,
  "msg": "success",
  "enMsg": null,
  "data": {
    "accessToken": "EXAMPLE_TOKEN_NOT_VALID",
    "refreshToken": "EXAMPLE_TOKEN_NOT_VALID",
    "tokenType": "polarstar",
    "userId": "a1b2c3d4-uuid",
    "username": "example_api_user",
    "orgId": "org-001",
    "groupId": "group-001",
    "isAdmin": false,
    "expiresIn": 1735689600000,
    "loginCode": "login-session-id",
    "switchableGroups": [
      {
        "groupId": "group-001",
        "groupName": "East Region"
      },
      {
        "groupId": "group-002",
        "groupName": "West Region"
      }
    ]
  }
}

Response Parameter Description

Response data: object containing the token and user identity on success.

Errors: data may be null, a string or an array of messages. Check the HTTP status and code before reading success data. See error handling.

Response:

Parameter Name	Type	Description
accessToken	string	Access token; include in the third-api-token header for subsequent requests
refreshToken	string	Refresh token (refresh API not available in the current version; can be ignored)
tokenType	string	Token type identifier
userId	string	User ID
username	string	Username
orgId	string	Organization ID
groupId	string / null	Selected Group ID; null when no Group is selected
isAdmin	boolean	Account role flag; no action is needed for API calls
expiresIn	long	Access token expiration time (timestamp in milliseconds)
loginCode	string	Session identifier (can be ignored)
switchableGroups	array	Available Groups; each item contains groupId and groupName
switchableGroups[].groupId	string	Group ID
switchableGroups[].groupName	string	Group name

Notes

• expiresIn represents the absolute expiration time of the token; the default validity period is 7,200 seconds (2 hours).
• After selecting a target group from switchableGroups, call the "switch current group" API to perform the switch.

Account prerequisites

Your account needs Third Party API Login enabled and an assigned Group. See Create an API user and Assign a group for setup steps.