Node.js中docusign-esign的JWT认证及API调用配置咨询

思路纠正 #

你当前使用的是应用级JWT令牌（token_type为Application），这类令牌仅适用于无需用户上下文的操作（比如查询账户基础信息、模板列表）。但调用getEnvelope这类接口需要绑定具体用户的上下文（信封属于特定用户/账号），因此必须切换为用户级JWT认证流程，而非尝试转换应用级令牌。

正确认证步骤与代码示例 #

用户级JWT认证需通过requestJWTUserToken方法获取Bearer令牌，具体操作如下：

1. 必要参数准备 #

除已有的integrationKey和privateKey，还需：

• userId：目标用户的API用户名（GUID格式），可从DocuSign控制台用户详情页获取。
• accountId：用户所属的账号ID，可从控制台用户详情或后续API调用中获取。
• scopes：必须包含signature和impersonation（模拟用户操作的核心权限）。

2. 修改后的代码 #

const apiClient = new ApiClient();
// OAuth认证服务路径为account-d.docusign.com
apiClient.setOAuthBasePath('https://account-d.docusign.com');
// Demo环境API基础路径
apiClient.setBasePath('https://demo.docusign.net/restapi');

const userId = 'YOUR_TARGET_USER_GUID';
const scopes = ['signature', 'impersonation'];
const token = await apiClient.requestJWTUserToken(
  integrationKey,
  userId,
  scopes,
  Buffer.from(privateKey),
  3600 // 令牌有效期，最长支持3600秒
);

// 将Bearer令牌添加到默认请求头
apiClient.addDefaultHeader('Authorization', `Bearer ${token.body.access_token}`);

// 调用getEnvelope接口示例
const envelopesApi = new EnvelopesApi(apiClient);
try {
  const envelope = await envelopesApi.getEnvelope('YOUR_ACCOUNT_ID', 'YOUR_ENVELOPE_ID');
  console.log('Envelope details:', envelope);
} catch (error) {
  console.error('API调用失败:', error);
}

DocuSign控制台必须完成的配置 #

• 集成密钥（IK）配置：
  • 启用JWT认证：在应用详情页的「认证」标签下开启JWT功能。
  • 添加重定向URI：填写任意有效URL（如https://localhost），用于首次JWT授权验证。
• 用户绑定：在应用详情页的「用户」标签下，将需要调用API的用户添加到该集成密钥的授权列表中。
• 首次JWT授权：
  • 在应用详情页的「授权」标签下，点击「授权」按钮，完成用户对应用权限的同意（仅需一次，Demo环境手动操作即可）。

关键说明 #

• 用户级JWT令牌的token_type为Bearer，可直接用于所有需要用户上下文的API调用。
• 需确保userId对应的用户拥有目标信封的访问权限（如信封创建者或被授权查看的用户）。

内容的提问来源于stack exchange，提问作者Svetoslav Petrov