Qi LogoMiniApps Docs
Development

Complete Authentication Flow

Full step-by-step authentication flow for SuperQi miniapps

This guide walks you through the complete authentication flow for SuperQi miniapps, covering both frontend and backend implementation. The authentication flow allows your miniapp to securely obtain user information and access tokens.

Overview

The authentication process consists of two main steps:

  1. Frontend: Obtain an authorization code from the user
  2. Backend: Exchange the authorization code for an access token

Important: The access token has a validity of 10 years, so you only need to perform this flow once per user and store the token securely.

Step 1: Frontend - Get Authorization Code

Implementation

On the frontend, use the my.getAuthCode method to request user authorization:

my.getAuthCode({
  scopes: ["auth_base"],
  success: (res) => {
    // Send res.authCode to your backend to exchange for access token
    console.log("Authorization Code:", res.authCode);
    // TODO: Implement your backend API call here
  },
  fail: (res) => {
    // Handle authorization failure
    console.error("Authorization failed:", res);
    // TODO: Implement your error handling here
  },
});

Scopes

For a complete list of available scopes and their descriptions, see the Frontend Documentation.

For more details about the frontend implementation, see the Frontend Documentation.

Step 2: Backend - Exchange Authorization Code for Access Token

API Endpoint

Make a POST request to exchange the authorization code for an access token:

URL: POST /v1/authorizations/applyToken

Request Body

{
  "grantType": "AUTHORIZATION_CODE",
  "authCode": "frontend_auth_code_here"
}

Request Headers

Ensure your request includes the proper authentication headers with signature:

Content-Type: application/json; charset=UTF-8
Client-Id: your_client_id
Request-Time: 2024-01-01T12:00:00-07:00
Signature: algorithm=RSA256, keyVersion=1, signature=base64_encoded_signature

Expected Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
  "accessTokenExpiryTime": "2034-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811xxxx",
  "refreshTokenExpiryTime": "2034-06-08T12:12:12+08:00",
  "customerId": "1000001119398804xxxx",
  "extendInfo": null
}

For detailed response parameter descriptions, see the applyToken API documentation.

Security Considerations

Important Security Notes:
  1. Store Access Tokens Securely: Access tokens are valid for 10 years and provide access to user data. Store them encrypted in your database.
  2. Validate Authorization Codes: Always validate that authorization codes are used only once and within a reasonable time frame.
  3. Private Key Security: Keep your merchant private key secure and never expose it in client-side code.
  4. HTTPS Only: Always use HTTPS for all authentication-related requests. ::

Additional Resources