Authentication (OAuth)

Overview

Tencent eSign OAuth 2.0 Authorization Service provides secure API access for application integrations.

Two authorization modes are supported depending on your integration scenario:

Mode	Grant Type	When to Use
Open Mode	`authorization_code` + PKCE	End-user authorization. The user logs in on the authorization page, selects a Space, and grants access.
Designated Space Mode	`authorization_code` + PKCE + `space_id`	Enterprise scenario. The Space is pre-determined; use `/members/add` to pre-add users before initiating OAuth.
Server-to-Server	`client_credentials`	Backend service calls on behalf of a Space. No user interaction required.

Used for third-party integrations where end-user authorization is required.

Steps:

Generate a PKCE code_verifier / code_challenge pair
Open GET /openapi/v1/oauth/auth in a WebView — user logs in, selects Space, clicks Agree
WebView redirects to your redirect_uri with an auth_code; intercept it
Exchange the auth_code for access_token + refresh_token
Use the access_token to call business APIs

redirect_uri: Supports custom schemes (e.g. myapp://oauth-callback) and HTTPS URLs. HTTP (plain) is not accepted.

For server-to-server integration. No user interaction required.

Token	TTL	Flows	Notes
access_token	1 hour	Both	JWT, stateless
refresh_token	Permanent	Authorization Code only	Rolling refresh — each use issues a new `refresh_token` and immediately invalidates the old one

Scopes are space-separated strings: envelope:create envelope:read

Currently supported scopes:

envelope:create — Create and send envelopes
envelope:read — Read envelope status and details
envelope:manage — Manage envelopes (create, send, download, view, etc.), superset of envelope:create + envelope:read, recommended for new integrations
stamp:manage — Manage stamps (create, edit, delete, view, etc.)
template:manage — Manage templates (create, edit, delete, use, etc.)
member:manage — Manage members (pre-add, activate, etc.)