关于DocuSign服务集成JWT认证流程及sub声明的技术咨询

Great question! Let's break down how DocuSign's JWT authentication handles the sub claim, based on the two core use cases:

1. Acting on behalf of a specific individual user #

• You must include the sub claim here, set to the target user's DocuSign userId.
• This is the standard impersonation flow—your app acts as that specific user, inheriting their permissions to send envelopes, manage their templates, access their account data, etc.
• Your current working setup falls into this category, which is why your JWT with a valid sub claim successfully retrieves an access token.

2. Acting as a system/service account (no user context) #

• This is exactly the scenario the blog post references: when your app runs as a standalone system identity (think backend automation, scheduled tasks that don’t tie to a specific human user, or account-wide administrative actions).
• In this case, you do omit the sub claim from your JWT payload.
• Important prerequisite: Your DocuSign integration must be configured to use a dedicated service account. You’ll need to set this up in the DocuSign Admin console, linking the service account to your app and ensuring it has the necessary system-level permissions to operate without a user context.

Key Notes to Avoid Issues #

• If you try to omit sub without configuring the service account first, your token request will fail—DocuSign needs a clear identity to authenticate when there’s no user being impersonated.
• Always align your JWT setup with your actual workflow:
  • Keep using sub if you need to act under a specific user’s permissions (e.g., sending envelopes from their email, accessing their saved templates).
  • Use the no-sub flow only for system-level tasks that don’t require tying to an individual user (e.g., managing account-wide templates, pulling account analytics).

内容的提问来源于stack exchange，提问作者Milica Stefanović