OAuth Authorization Flow
Complete flows, sequence designs, and token lifecycle management for the two authorization modes.
For complete field descriptions of each OAuth API, see OAuth Module - Overview. This page focuses on the complete guide for integrators implementing OAuth, including mode selection, the full sequence of Designated Space Mode, and token lifecycle management.
Authorization Mode Selection
| Dimension | Open Mode | Designated Space Mode |
|---|---|---|
| Applicable scenario | C-end users; each email initiates authorization independently | Enterprise/organization scenarios; the user’s Space is pre-designated by the integrator |
Whether authorization URL includes space_id | No | Yes (with login_hint simultaneously) |
| Whether users need to be pre-added | No (if unregistered, silently registered and a default Space is created) | Yes (must call the Pre-add Members API first) |
| Whether authorization page shows Space selector | Yes | No (Space is locked by the server) |
| Auto-creation of Space | Yes (on first authorization by an unregistered user) | No |
When the integrator needs to strictly assign users to a specific enterprise Space, choose Designated Space Mode; otherwise, default to Open Mode and let the user select or have the system create a Space.
Authorization Flow Diagram
Exception branches (user cancellation, authorization rejection, account disabled / Space locked, etc.) return a 302 to redirect_uri with error=access_denied per RFC 6749 §4.1.2.1. The Get Started page silently registers new users and creates a default Space (the user is the admin); existing users see the list of Spaces they have joined (with role and installation status annotated) after login, and select one themselves.
Sequence Diagram
client_secret and refresh_token involve credential storage and should be kept within the integrator’s trusted domain. The specific storage and substitution boundaries are determined by the integrator based on its own architecture.
Designated Space Mode
Designated Space Mode adds a “member pre-addition” prerequisite step on top of Open Mode, and automatically activates pending members during the SubmitConsent stage.
The two activation paths do not affect each other: users can activate membership by clicking “Agree” on the OAuth authorization page, or by directly clicking the link in the invitation email. Both methods are valid; whichever completes first takes effect.
Token Lifecycle
| Scenario | Behavior |
|---|---|
| access_token expires | Use refresh_token to exchange for a new access_token + new refresh_token |
| refresh_token never expires | No re-authorization needed (call revoke if leaked) |
| User revokes integration app authorization on Tencent eSign side | The user/Space’s access_token and refresh_token are immediately blacklisted and invalidated; subsequent business API calls will return 401 invalid_token. The integrator should clean up the corresponding local token and re-initiate OAuth the next time the user uses the app |
| Same user re-initiates OAuth on a new device and completes authorization | The old refresh_token does not immediately expire; old and new tokens may coexist; the specific retention policy is subject to server implementation |
| Integrator actively revokes token | Call the Token Revocation Endpoint |
Each refresh_token refresh returns a new refresh_token, and the old value is immediately invalidated (rolling refresh). Please replace the original value with the new one; otherwise, the next refresh will fail. The returned token is already bound to the Space selected on the authorization page; no need to pass space_id when calling business APIs.
Scope Values
| scope | Description |
|---|---|
envelope:create | Create and send an envelope (required for “Initiate Signing”) |
envelope:read | Read envelope list and status (required for “Signing Status”) |
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.) |
If new scopes are added in the future, they will be announced via version updates and will not break existing scope semantics.