Authorization Endpoint

GET/openapi/v1/oauth/auth

Initiates the OAuth 2.0 Authorization Code flow. Open this URL in a WebView — the user will be directed to the Tencent eSign authorization page to log in, select a Space, and grant authorization.

After the user clicks Agree, the server redirects to your redirect_uri with an authorization code. Pass this code to POST /openapi/v1/oauth/token to obtain tokens.

Two modes: - Open Mode (default): Do not pass space_id. The user selects their own Space on the authorization page. If login_hint is an unregistered email, the system silently registers a new account. - Designated Space Mode: Pass both space_id and login_hint. The target Space is locked server-side; the user cannot switch Spaces. The user must have been pre-added via POST /openapi/v1/members/add before initiating authorization — otherwise the authorization will be rejected with access_denied.

PKCE is required (code_challenge_method=S256). Plain is not supported.

Request Parameters

Query Parameters

client_idRequiredstring

Your app's `client_id`, obtained from the Tencent eSign console.

response_typeRequiredstring

Must be `code`.

redirect_uriRequiredstring

The URI to redirect to after authorization. Must exactly match the value registered in the console. Supports custom schemes (e.g. `myapp://oauth-callback`) and HTTPS URLs.

code_challengeRequiredstring

`base64url(SHA-256(code_verifier))`. Generated by your app as part of the PKCE flow.

code_challenge_methodRequiredstring

Must be `S256`. Plain is not supported.

stateOptionalstring

**Strongly recommended.** A random string (≥ 32 bytes) generated by your app. Returned as-is in the callback. Verify it matches before exchanging the code — this prevents CSRF attacks.

scopeOptionalstring

Space-separated scopes to request. If omitted, defaults to all scopes granted to this app.

login_hintOptionalstring

Pre-fills the email field on the authorization page. In **Open Mode**, if the email is not yet registered, the system silently registers a new account. In **Designated Space Mode**, must match the email passed to `/members/add`.

space_idOptionalstring

**Designated Space Mode only.** When provided, the target Space is locked server-side — the user cannot switch Spaces on the authorization page. Requires the user to have been pre-added via `POST /openapi/v1/members/add`. If the user was not pre-added, authorization is rejected with `access_denied`.

langOptionalstring

UI language. Allowed values: `en` (English), `zh-CN` (Simplified Chinese), `zh-HK` (Traditional Chinese), `id` (Indonesian), `ms` (Malay), `th` (Thai), `vi` (Vietnamese). When provided, the backend passes it through to the frontend authorization page and login page to control the interface language. If omitted, English is used by default.

Response Parameters

Redirects to the authorization page. After the user completes authorization, redirects back to redirect_uri.

Authorization granted:

{redirect_uri}?code=AUTH_CODE&state=ECHOED_STATE

The code is valid for 10 minutes and can only be used once. Pass it to POST /openapi/v1/oauth/token immediately.

User cancelled or authorization denied:

{redirect_uri}?error=access_denied&state=ECHOED_STATE

Other errors (e.g. invalid client_id, mismatched redirect_uri):

{redirect_uri}?error=invalid_request&error_description=...&state=ECHOED_STATE

Introduction Token Endpoint