Get or Refresh Token

POST 
/auth/v1/token

API Description

Get or refresh token API, supports multiple OAuth 2.0 standard authorization modes, used to obtain access_token and refresh_token.

Authorization Mode Description

1. Refresh Token Refresh Mode

Input Requirements:

• grant_type: Authorization type (required, fixed value "refresh_token")
• refresh_token: Refresh token (required, used to obtain new access_token)
• client_id: Client ID corresponding to the application (optional, defaults to environment ID)
• x-device-id: Device ID (optional, passed in request header)

Prerequisites:

• Must hold a valid refresh_token
• refresh_token is not expired and not revoked

Output:

• token_type: Token type, fixed as "Bearer"
• access_token: Access token, used to access protected resources
• refresh_token: New refresh token, original refresh_token becomes invalid immediately
• expires_in: access_token expiration time (seconds)
• sub: User unique identifier

Refresh Token Refresh Request Example

{
  "client_id": "demo-app-2f8a9c3e1b4d",
  "grant_type": "refresh_token",
  "refresh_token": "m.pQ1rS2tU3vW4xY5zA6bC7dE8fG9hI0jK1lM2nO3pQ4rS5tU6vW7xY8zA9bC0dE1fG2hI3jK4lM5nO6"
}

Refresh Token Refresh Response Example

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "refresh_token": "m.aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ5aB6cD7eF8gH9iJ0kL1mN2oP3qR4sT5uV6wX7yZ8",
  "expires_in": 7200,
  "sub": "9876543210123456789"
}

2. Password Mode Authentication

Input Requirements:

• grant_type: Authorization type (required, fixed value "password")
• username: Username (required)
• password: Password (required)
• client_id: Client ID corresponding to the application (optional, defaults to environment ID)
• x-device-id: Device ID (optional, passed in request header)

Prerequisites:

• User is registered and password is set
• Username/password login method is enabled

Output:

• token_type: Token type, fixed as "Bearer"
• access_token: Access token
• refresh_token: Refresh token
• expires_in: access_token expiration time (seconds)
• sub: User unique identifier

Password Mode Request Example

{
  "client_id": "demo-app-2f8a9c3e1b4d",
  "grant_type": "password",
  "username": "zhangsan",
  "password": "9aBr6rULgNMhLyE"
}

Password Mode Response Example

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "refresh_token": "m.aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ5aB6cD7eF8gH9iJ0kL1mN2oP3qR4sT5uV6wX7yZ8",
  "expires_in": 7200,
  "sub": "9876543210123456789"
}

3. Client Credentials Mode

Input Requirements:

• grant_type: Authorization type (required, fixed value "client_credentials")
• client_id: Client ID corresponding to the application (optional, defaults to environment ID)
• Authorization: Authentication information (required, passed in request header, format "Basic ${base64(SecretId:SecretKey)}")

Prerequisites:

• Must hold valid SecretId and SecretKey
• Caller must have trusted server-side environment
• SecretKey must be stored in secure medium

Output:

• token_type: Token type, fixed as "Bearer"
• access_token: Access token with super administrator privileges
• expires_in: access_token expiration time (seconds)
• Note: Does not return refresh_token

Client Credentials Mode Request Example

POST /auth/v1/token
Authorization: Basic bG93Y29kZS01ZzlhYzIwdTJhMjdkYTQ2OnNlY3JldF9rZXlfZXhhbXBsZQ==
Content-Type: application/json

{
  "client_id": "demo-app-2f8a9c3e1b4d",
  "grant_type": "client_credentials"
}

Client Credentials Mode Response Example

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "expires_in": 7200
}

Field Description

Request Parameters

Field Name	Type	Required	Description
grant_type	string	Yes	Authorization type, optional values: refresh_token, password, client_credentials
refresh_token	string	No	Refresh token, required when grant_type is refresh_token
username	string	No	Username, required when grant_type is password
password	string	No	Password, required when grant_type is password
client_id	string	No	Client ID, defaults to environment ID
x-device-id	string	No	Device ID, passed in request header
Authorization	string	No	Authentication information, required when grant_type is client_credentials, passed in request header

Response Parameters

Field Name	Type	Description
token_type	string	Token type, fixed as "Bearer"
access_token	string	Access token, used to access protected resources
refresh_token	string	Refresh token, used to obtain new access_token (not returned in client_credentials mode)
expires_in	integer	access_token expiration time (seconds)
sub	string	User unique identifier (service_account in client_credentials mode)

Key Characteristics

Refresh Token Refresh Mechanism

• Conforms to RFC 6749 Section 6 standard
• Original refresh_token becomes invalid immediately after use
• Returns new access_token and refresh_token
• Supports seamless refresh, improving user experience

Password Mode

• Conforms to RFC 6749 Section 4.3 standard
• Suitable for trusted clients
• Directly uses username and password to obtain token
• Returns access_token and refresh_token

Client Credentials Mode

• Conforms to RFC 6749 Section 4.4 standard
• Suitable for server-side calls
• Automatically grants super administrator privileges
• Does not return refresh_token
• Requires SecretId and SecretKey authentication

Security Specifications

Refresh Token Security

• refresh_token should be stored securely on the client
• Becomes invalid immediately after use, preventing replay attacks
• Recommend regular rotation of refresh_token
• Should be revoked immediately when anomalies are detected

Password Mode Security

• Use only in trusted clients
• Password should be encrypted during transmission (HTTPS)
• Recommend implementing login failure count limit
• Support verification code protection mechanism

Client Credentials Mode Security

• SecretKey must be stored in secure medium
• Use only in trusted server-side environment
• Regularly rotate SecretKey
• Record all call audit logs
• Limit call frequency and IP whitelist

Usage Scenarios

Refresh Token Refresh

• Automatically refresh when access_token is about to expire
• Implement seamless login experience
• Maintain long-term login state

Password Mode

• User first login
• Trusted first-party applications
• Internal management systems

Client Credentials Mode

• Server-side API calls
• Backend management operations
• System integration scenarios
• Operations requiring administrator privileges

Notes

General Notes

• All modes require HTTPS transmission
• access_token should be stored in memory, not recommended for persistence
• refresh_token should be stored securely to prevent leakage
• Regularly check token validity

Refresh Token Notes

• Original refresh_token becomes invalid immediately after use
• Need to handle refresh_token expiration
• Recommend refreshing before access_token expires

Password Mode Notes

• Not recommended for third-party applications
• Need to implement password security policy
• Recommend using with verification code

Client Credentials Mode Notes

• Use only on server-side, not on client-side
• SecretKey leakage will cause serious security issues
• Need to implement IP whitelist restriction
• Recommend implementing call frequency limit

Request

Query Parameters

client_id string

Client ID corresponding to the application, defaults to environment ID, can be omitted

Header Parameters

x-device-id string

Device ID, the ID of the current logged-in device. The client should generate it randomly and cache it on the client. This parameter is related to the number of logged-in accounts.

application/json

Body

grant_type Grant type for obtaining token (string)nullable
code Used when grant_type is authorization_code (string)
refresh_token Used when refreshing token via refresh_token (string)
username Used when grant_type is password (string)
password Used when grant_type is password (string)
scope scope, optional (string)
nonce Nonce string, optional (string)
code_verifier PKCE: code_verifier (string)
device_code Device Code Flow https://tools.ietf.org/html/rfc8628 (string)

Responses

200

A successful response.

Response Headers

application/json

Schema

Schema

token_type Access token type (string)

Uniformly return Bearer

access_token User's access token (string)

Token used to access Cloud Development HTTP API, length within 4096 bits

refresh_token User's refresh token (string)

access_token can be refreshed to get a new access_token when it expires through refresh_token, expiration time defaults to 31 days. Length within 128 bits

expires_in int32

Expiration time of access_token, in seconds

scope Authorization scope (string)
sub User's unique ID (string)
groups string[]

Example (from schema)

{
  "token_type": "string",
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 0,
  "scope": "string",
  "sub": "string",
  "groups": [
    "string"
  ]
}

500

An unexpected error response.

Response Headers

application/json

Schema

Schema

error Error message (string)
error_code int32
error_description Error description (string)

Example (from schema)

{
  "error": "string",
  "error_code": 0,
  "error_description": "string"
}

Loading...