Switch group

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

Use Content-Type: application/json and optionally X-Locale: en. The third-api-token header is required. See common headers and error handling.

Brief Description

• Allows a logged-in user to switch the currently active Group.
• Returns a new Access Token upon successful switching; subsequent OpenAPI requests must use this new token.

Request URL

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

Request Method

• POST

Parameters

Request Body:

Parameter Name	Required	Type	Description
groupId	Yes	string	Target Group ID from the login response's switchableGroups list

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-002",
    "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 replacement token and selected group 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 fields:

Parameter Name	Type	Description
accessToken	string	New access token
refreshToken	string	Refresh token field; no refresh endpoint is available in this version
tokenType	string	Token type identifier; send the raw access token in third-api-token
userId	string	User ID
username	string	Login name
orgId	string	Organization ID
groupId	string / null	Selected Group ID after switching
isAdmin	boolean	Account role flag; no action is needed for API calls
loginCode	string	Session identifier
switchableGroups	array	Assigned Group options; same structure as Log in
switchableGroups[].groupId	string	Group ID
switchableGroups[].groupName	string	Group name
expiresIn	long	Expiration time of the new Token (timestamp in milliseconds)

Notes

• Upon a successful switch, you must immediately replace the third-api-token in the header with the new accessToken.