Quickstart
Minimally run through two paths: initiate signing and view signing status.
Prerequisites
Environment
Tencent eSign currently provides only the Singapore production environment; sandbox environment and other regions are not yet available.
| Purpose | Domain |
|---|---|
| Open API base URL | https://sgapi.tencent-esign.com |
| OAuth Consent frontend page | Auto-redirected via 302 from /openapi/v1/oauth/auth; no need to construct manually |
| Embedded page | Full URL returned by /openapi/v1/embedded/views; no need to construct manually |
For integration testing, please use the integrator’s own test email and low-value scenarios. Credentials are issued per region: currently only Singapore is available. When expanding in the future, the integrator must register an account and create an app in the new region; credentials are not reusable across regions.
Credential Preparation
After completing the following steps in the Tencent eSign console, the integrator can obtain access credentials:
- Register an account — The integrator’s responsible person registers an account in the Tencent eSign console, which automatically creates an integrator Space (the registrant becomes the admin of that Space)
- Bind a billing resource package — Purchase the required regional billing resource package within the integrator Space (see the console instructions for the specific purchase process)
- Create an OAuth App — Create a third-party application on the App management page, filling in the App name,
redirect_uri, requestedscope, and branding information (see Embedded Views - Branding). After creation, the console displaysclient_idandclient_secret(client_secretis shown only once; please save it securely immediately; it can be reset in the console later) - Multi-region access — Complete steps 1–3 independently in each region; credentials / resource packages are not reusable across regions
| Resource | Required | Description |
|---|---|---|
client_id | Yes | Generated when creating an app in the console |
client_secret | Yes | Generated when creating an app in the console; shown only once; keep it secure; can be reset in the console after leakage |
redirect_uri | Yes | Filled in when creating the app; custom scheme or HTTPS URL (plain http:// callbacks are not accepted); must exactly match the value passed when initiating authorization; modify in the console |
| Branding configuration | No | Submitted together when creating the app; see Embedded Views - Branding |
A single client_id can be authorized and installed by multiple user Spaces; the authorization and signing data of each user Space are isolated from each other.
Step Overview
A. Initiate Signing
First-time access requires completing OAuth authorization:
[1] Integrator application generates PKCE
[2] Integrator application opens WebView to load the authorization URL
[3] User completes login, selects Space, and clicks Agree on the Consent page
[4] WebView is 302-redirected to myapp://oauth-callback?code=...; integrator application intercepts
[5] Integrator application exchanges code for access_token + refresh_token
[6] Integrator application calls /openapi/v1/files/upload with access_token to upload the file to be signed and obtains FileId
[7] Integrator application calls /openapi/v1/embedded/views with access_token, includes FileId in the request body, and obtains the embedded page URL
[8] Integrator application opens WebView to load the embedded page URL; the user completes envelope initiation in the embedded pageB. View Signing Status
OAuth authorization must be completed first to obtain an access_token:
[1] Integrator application reuses the local access_token (if expired, uses refresh_token to get a new one)
[2] Integrator application calls /openapi/v1/embedded/views (OperateType=signature_status) to obtain the embedded page URL
[3] Integrator application opens WebView to load the URL, displaying the contract list of the current user under the selected SpacePKCE Generation
// Generated by the integrator application
const verifier = base64url(randomBytes(64)); // 43~128 characters
const challenge = base64url(sha256(verifier)); // PKCE S256
// Store verifier in memory or secure storage; challenge is used in the next stepOpen the Authorization URL
https://sgapi.tencent-esign.com/openapi/v1/oauth/auth
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=myapp%3A%2F%2Foauth-callback
&code_challenge=CHALLENGE
&code_challenge_method=S256
&state=RANDOM_NONCE
&scope=envelope%3Acreate%20envelope%3AreadExchange Code for Token
curl -X POST https://sgapi.tencent-esign.com/openapi/v1/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code\
&code=AUTH_CODE_FROM_CALLBACK\
&code_verifier=VERIFIER_FROM_PKCE_STEP\
&client_id=YOUR_CLIENT_ID\
&client_secret=YOUR_CLIENT_SECRET\
&redirect_uri=myapp%3A%2F%2Foauth-callback"{
"access_token": "AT_xxx",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "RT_xxx",
"scope": "envelope:create envelope:read"
}Upload File
The integrator application (outside the WebView) calls the upload API with access_token to obtain a FileId:
curl -X POST https://sgapi.tencent-esign.com/openapi/v1/files/upload \
-H "Authorization: Bearer AT_xxx" \
-H "Content-Type: application/json" \
-d '{
"Files": [
{ "FileName": "contract.pdf", "FileBody": "<Base64-encoded content>" }
]
}'{
"Response": {
"RequestId": "req_01HJ8XYZ...",
"Data": {
"Files": [
{ "FileId": "DOC_xxx", "FileName": "contract.pdf" }
]
}
}
}The returned FileId is bound to the webview token via OperateParam.FileIds when exchanging for the embedded page URL.
Exchange for Embedded Page URL
curl -X POST https://sgapi.tencent-esign.com/openapi/v1/embedded/views \
-H "Authorization: Bearer AT_xxx" \
-H "Content-Type: application/json" \
-d '{
"OperateType": "request_signatures",
"OperateParam": { "FileIds": ["DOC_xxx"] }
}'{
"Response": {
"RequestId": "req_01HJ8XYZ...",
"Data": {
"Url": "https://<frontend-host>/console/envelopes/edit/EV_xxx?EmbeddedToken=xxx",
"ExpiresAt": "2026-06-24T11:00:00Z"
}
}
}The integrator application opens Url in a WebView; see Embedded Views for the remaining flow.
View Signing Status
Reuse the existing access_token and call the same /embedded/views endpoint, changing OperateType to signature_status:
curl -X POST https://sgapi.tencent-esign.com/openapi/v1/embedded/views \
-H "Authorization: Bearer AT_xxx" \
-H "Content-Type: application/json" \
-d '{ "OperateType": "signature_status" }'The response structure is the same as the previous step (Url + ExpiresAt). Opening Url in a WebView displays the contract list of the current user under the selected Space.
Designated Space Mode
For enterprise/organization scenarios where the user’s Space is pre-designated by the integrator. Before the OAuth authorization step above, complete member pre-addition:
[0] Integrator application calls /openapi/v1/members/add with access_token to pre-add the target user as a pending member (an invitation email is sent simultaneously)
[1] Integrator application generates PKCE (same as above)
[2] Integrator application opens WebView to load the authorization URL (with additional space_id + login_hint)
[3] User logs in on the Consent page and clicks "Agree" (no Space selection step; clicking Agree is treated as accepting the invitation and automatically activates the member)
[4] WebView is 302-redirected to redirect_uri?code=...; integrator application intercepts
[5-8] Subsequent steps are identical to Open Mode (exchange token → upload file → exchange for embedded page URL → initiate signing)Users can also complete activation by directly clicking the invitation email link without going through OAuth authorization; the two paths do not affect each other. For the complete sequence diagram, see OAuth Authorization Flow - Designated Space Mode.