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": "your_access_token",
  "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": "your-password"
}

Password Mode Response Example

{
  "token_type": "Bearer",
  "access_token": "your_access_token",
  "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": "your_access_token",
  "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

Responses

200

A successful response.

Response Headers

500

An unexpected error response.

Response Headers