Authentication

All business API requests must include an OAuth 2.0 access token for identity verification.

Authentication Method

All business endpoints require a Bearer Token in the HTTP header:

Authorization: Bearer <access_token>

Example request (get envelope detail):

curl -X POST 'https://sgapi.tencent-esign.com/openapi/v1/envelopes/detail' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJHU0lfeHh4In0.signature' \
  -H 'Content-Type: application/json' \
  -d '{"EnvelopeId": "SGEVxxxxxxxxxxxxxxxxxxxxxx"}'

Two Authorization Modes

Tencent eSign supports two OAuth 2.0 grant types:

Authorization Code + PKCE (for third-party integrations)

Used when end-user authorization is required (e.g. WPS integration). The user logs in on the Consent page, selects a Space, and grants access. Returns both access_token (1h) and refresh_token (permanent).

See the Authorization Endpoint and Token Endpoint for full details.

Client Credentials (server-to-server)

For backend service integration without user interaction. Use your app’s client_id and client_secret to request an access_token directly.

POST https://sgapi.tencent-esign.com/openapi/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&space_id=YOUR_SPACE_ID&scope=envelope:create envelope:read

⚠️

Keep your client_secret secure. Never expose it in frontend code or public repositories. Use environment variables or a key management service instead.

💡

The access_token is valid for 1 hour. Cache the token and request a new one approximately 60 seconds before expiry. The Client Credentials grant does not issue a refresh_token — request a new token when it expires.

For complete parameters and error codes, see the Token Endpoint API Reference.

Revoking a Token

When a token is no longer needed, actively revoke it to invalidate it immediately.

Revoking a refresh_token also immediately invalidates all access_tokens derived from it.

POST https://sgapi.tencent-esign.com/openapi/v1/oauth/revoke
Content-Type: application/x-www-form-urlencoded
 
token=YOUR_TOKEN&token_type_hint=access_token&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

For complete details, see the Token Revocation API Reference.

Scopes

Currently supported scopes:

Scope	Description
`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`
`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.)

Separate multiple scopes with spaces, e.g.: envelope:create envelope:read

Business API Request Headers

After obtaining an access_token, include the following headers when calling business APIs:

Header Parameters

AuthorizationRequiredstring

Bearer <access_token>

Content-TypeRequiredstring

application/json

X-Operator-User-IdOptionalstring

Operator user ID. Not required in Authorization Code mode — the authorized user's ID is used automatically. Required for some endpoints in Client Credentials mode.

ℹ️

These headers apply to business APIs only. OAuth token endpoints (issue/revoke) use application/x-www-form-urlencoded and do not require the Authorization header.

Error Responses

Token endpoint error responses follow the RFC 6749 §5.2 format. See the Token Endpoint API Reference for details.

Call Method Response Format