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>

Obtaining an access_token

Tencent eSign Open API uses the OAuth 2.0 Client Credentials grant type. Use your app’s client_id and client_secret to request an access_token from the token endpoint.

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 to avoid frequent token endpoint calls.

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

Revoking an access_token

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

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

For complete request parameters and response 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

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 (defaults to system user ID if omitted)

ℹ️

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