OAuth2 Integration Guide

OAuth2 allows third-party applications to access users' MindVerse data after authorization. This guide explains how to implement the standard authorization code flow.

Overview

SecondMe API uses the standard OAuth2 Authorization Code Flow:

1. User is redirected to MindVerse authorization page
2. User confirms authorization
3. MindVerse returns authorization code to your application
4. Your application exchanges the code for Access Token
5. Use Access Token to call APIs

Authorization Flow Diagram

The following diagram illustrates the complete OAuth2 Authorization Code Flow:

Prerequisites

Before you begin, you need to:

1. Register your application in SecondMe Developer Console
2. Obtain client_id and client_secret
3. Configure callback URL (Redirect URI)

Token Types and Validity

Authorization Flow

Step 1: Initiate Authorization Request

Guide the user to the SecondMe authorization page for login and authorization.

Option A: Frontend Redirect (Recommended)

For web applications, we recommend using the standard OAuth2 redirect approach. Redirect the user to the SecondMe authorization page:

https://go.second-me.cn/oauth/?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&state=RANDOM_STATE

Authorization URL Parameters:

Frontend Example Code:

// Build authorization URL
function buildAuthorizationUrl() {
  const params = new URLSearchParams({
    client_id: 'your_client_id',
    redirect_uri: 'https://your-app.com/callback',
    response_type: 'code',
    state: generateRandomState()  // Generate and store random state for verification
  });
  return `https://go.second-me.cn/oauth/?${params.toString()}`;
}

// Initiate authorization - Option 1: Direct redirect
window.location.href = buildAuthorizationUrl();

// Initiate authorization - Option 2: Open in new window
window.open(buildAuthorizationUrl(), '_blank');

After the user completes login and authorization on SecondMe, they will be redirected back to your redirect_uri with the authorization code in the URL:

https://your-app.com/callback?code=lba_ac_xxxxx...&state=your_state

Important: Upon receiving the callback, always verify that the state parameter matches the value stored when initiating the request to prevent CSRF attacks.

Option B: Server-side Direct Call (For scenarios with existing user session)

If your server already has the user's login session (Bearer Token), you can directly call the authorization endpoint:

curl -X POST "https://api.mindverse.com/gate/lab/api/oauth/authorize/external" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your_client_id",
    "redirectUri": "https://your-app.com/callback",
    "scope": ["userinfo", "chat.read", "chat.write"],
    "state": "random_state_for_csrf_protection"
  }'

Request Parameters:

Success Response:

{
  "code": 0,
  "data": {
    "code": "lba_ac_xxxxx...",
    "state": "random_state_for_csrf_protection"
  }
}

Step 2: Exchange Code for Token

After receiving the authorization code, exchange it for Access Token on your server:

curl -X POST "https://api.mindverse.com/gate/lab/api/oauth/token/code" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=lba_ac_xxxxx..." \
  -d "redirect_uri=https://your-app.com/callback" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Note: The request body must use application/x-www-form-urlencoded format. Do NOT use JSON format (application/json). Using the wrong format will result in a Field required validation error.

Request Parameters:

Success Response:

{
  "code": 0,
  "data": {
    "accessToken": "lba_at_xxxxx...",
    "refreshToken": "lba_rt_xxxxx...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "scope": ["userinfo", "chat.read", "chat.write"]
  }
}

Step 3: Use Access Token

Use the Access Token in API requests:

curl -X GET "https://api.mindverse.com/gate/lab/api/secondme/user/info" \
  -H "Authorization: Bearer lba_at_xxxxx..."

Step 4: Refresh Access Token

When the Access Token expires, use the Refresh Token to get a new one:

curl -X POST "https://api.mindverse.com/gate/lab/api/oauth/token/refresh" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=lba_rt_xxxxx..." \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Note: The request body must use application/x-www-form-urlencoded format. Do NOT use JSON format (application/json). Using the wrong format will result in a Field required validation error.

Request Parameters:

Success Response:

{
  "code": 0,
  "data": {
    "accessToken": "lba_at_new_token...",
    "refreshToken": "lba_rt_new_token...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "scope": ["userinfo", "chat.read", "chat.write"]
  }
}

Note: Token refresh also rotates the Refresh Token. The old Refresh Token becomes invalid.

Permissions (Scope)

You need to specify permission list when requesting authorization. Users can see the permissions your application requests and decide whether to authorize.

Best Practice: Only request necessary permissions to avoid users rejecting authorization due to excessive permission requests.

Error Handling

Invalid or Expired Authorization Code

{
  "code": 400,
  "message": "Authorization code is invalid or expired",
  "subCode": "oauth2.code.invalid"
}

Client Secret Mismatch

{
  "code": 401,
  "message": "Client Secret does not match",
  "subCode": "oauth2.client.secret_mismatch"
}

Redirect URI Mismatch

{
  "code": 400,
  "message": "Redirect URI does not match",
  "subCode": "oauth2.redirect_uri.mismatch"
}

Access Token Expired

{
  "code": 401,
  "message": "Access Token has expired",
  "subCode": "oauth2.token.expired"
}

Security Best Practices

1. Protect Client Secret

Client Secret must be kept confidential and used only server-side. Never expose it in client-side code.

2. Validate Redirect URI

Ensure Redirect URI uses HTTPS and is registered in the Developer Console.

Local Development: Localhost redirect URIs (http://localhost:* and http://127.0.0.1:*) are automatically allowed during the OAuth2 authorization flow without being registered in the Developer Console. This makes local development easier — you can use any localhost port without updating your app configuration each time.

3. Store Tokens Securely

• Encrypt tokens when storing server-side
• Never log tokens
• Set appropriate expiration times

Online Debugger

We provide an interactive tool to test the complete OAuth2 Authorization Code Flow directly in your browser.

Open OAuth2 Online Debugger →

Next Steps

• OAuth2 API Reference - View complete API specifications
• SecondMe API Reference - Explore available API endpoints
• Error Codes Reference - Understand all error codes