{
  "schema": "aaes/capability-pack/1",
  "provider": "docusign",
  "version": "1.0.0",
  "description": "Docusign eSignature: read envelopes, templates and users, and create-and-send an envelope for signature in one account.",
  "notes": "The endpoint host 'docusign-account.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the account's own eSignature base URI host before enabling, in the endpoints, the resource locators and the egress allowlist — the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step. Docusign assigns each account a per-region account server; the real substitution shape is '{server}.docusign.net' (for example 'na4.docusign.net'; the demo environment is 'demo.docusign.net'), and the deployment obtains the account's base URI from the OAuth userinfo response.\n\nACCOUNT_ID in the endpoint paths is a placeholder for the Docusign account id: replace it before enabling. This pack registers only endpoints the official eSignature REST API v2.1 reference (and Docusign's published OpenAPI specification) documents: searching envelopes by status and date (listStatusChanges), listing templates, listing users, and creating an envelope. Reads are collection reads: single-record reads (GET.../envelopes/{envelopeId}, GET.../templates/{templateId}, GET.../users/{userId}), document and recipient retrieval, and audit events are not registered by this pack.\n\nDocumented exclusions: this pack does not register envelope update (PUT.../envelopes/{envelopeId}, which can send a draft, void an in-flight envelope or purge documents), recipient modification, bulk-send operations, Connect webhook configuration, template creation, and user creation, update or closure — deliberate exclusions, not approximated capabilities. Envelope content is contractual material about identifiable signers, so envelope data is classified as pii (personal data). The custody review that docs/gtm/CAPABILITY-LIBRARY-PLAN.md §4 gates authentication modes on was completed on 2026-09-21 against this pack's custody model (an OAuth access token held in the customer's vault and refreshed by an external process), with these findings, one per gated property.\n\nIssuance authority and delegation: tokens are minted by the Docusign authentication service, and the two grant types differ in whose identity the token carries — Authorization Code Grant acts on behalf of the individual user who granted consent and is present to authenticate, while JWT Grant impersonates a specific user on a long-term basis and is issued only after documented consent (individual consent, or admin consent via Docusign Admin for an organization).\n\nScope: least privilege is 'signature' for Authorization Code Grant and 'signature impersonation' for JWT Grant with its consent requirement; the 'extended' scope is a documented special scope for Authorization Code Grant integrations whose rolling behavior renews the refresh token's 30-day lifetime on each use, not a generic requirement for unattended refresh. Audience: the retrieved docs document no audience claim — the bearer value authorizes against the account's own base URI host, and audience binding beyond that is not established.\n\nTTL: Authorization Code Grant tokens expire after eight hours by default and come with a refresh token (30-day lifetime, extended on each use where the extended scope applies); JWT Grant tokens expire after one hour and the flow grants no refresh token, so each renewal builds a new JWT and exchanges it.\n\nRefresh ownership: minting and refresh are owned by an external deployment process that writes the fresh header value into the vault; the executor injects the stored value verbatim and performs no token lifecycle itself, and a stale value fails closed.\n\nRevocation: token revocation is an external operation against the Docusign authentication service, as the credential note states; the retrieved pages do not enumerate a finer revocation contract, so none is claimed. Executor access and replay/exposure: the executor reads only the vault reference; tokens are bearer credentials replayable while valid, and the one-hour and eight-hour TTLs bound the replay window.\n\nAlternate access paths: the Docusign web UI and other grants retain access outside this pack, and revoking this grant closes only this path. The custody gate is documented and passed; remaining owner placeholders bind at deployment.",
  "credential": {
    "secret_ref_id": "secret-ref-docusign-oauth-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "A Docusign OAuth 2.0 access token, held in the client's own secret manager. The stored material must be the complete Authorization header value: the scheme 'Bearer', one separating space, then the access token — 'Bearer <token>'. customer_vault is the only generally-supported production custody model here — identity_federation and customer_broker are refused at startup and inline is lab-only. Two grant types produce the stored token, and they differ in whose identity the token carries.\n\nAuthorization Code Grant (Confidential, or Public with PKCE): the integration acts on behalf of the individual user who granted consent and is present to authenticate; tokens expire after eight hours by default and come with a refresh token. JWT Grant: a service integration that impersonates (acts as) a specific user on a long-term basis without that user being present — it requires the 'signature' scope plus the 'impersonation' scope, and Docusign issues tokens only after documented consent to act on behalf of the impersonated user (individual consent, or admin consent via Docusign Admin for an organization); JWT Grant tokens expire after one hour and the flow grants no refresh token, so each renewal builds a new JWT and exchanges it.\n\nMinting and refresh must be owned by an external deployment process that writes the fresh header value into the vault — the executor injects the stored value verbatim and performs no token lifecycle itself, and a stale value fails closed. Token revocation is likewise an external operation against the Docusign authentication service.\n\nLeast privilege: request only the scopes these capabilities need — 'signature' for Authorization Code Grant, or 'signature impersonation' for JWT Grant with its consent requirement. The 'extended' scope is not a generic requirement for unattended refresh: Docusign documents it as a special scope for Authorization Code Grant integrations, and the documented rolling behavior is that refreshing with the extended scope renews the refresh token's 30-day lifetime on each use — sustained use keeps the grant alive without re-consent, while 30 days of inactivity expires it.\n\nRequest it only where that documented refresh-lifetime behavior applies.\n\nExecutor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack."
  },
  "capabilities": [
    {
      "capability_id": "docusign.envelopes.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "docusign-account.invalid"
      ],
      "endpoint": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/envelopes",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-docusign-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "docusign-account-envelopes",
      "description": "Search envelopes by status, date range and other filters (listStatusChanges): envelope ids, subjects, statuses and signer information — contractual material about identifiable people, classified as pii (personal data).\n\nThe registered path covers the collection read only — single-envelope reads (GET.../envelopes/{envelopeId}) and document retrieval are not registered by this pack.\n\nACCOUNT_ID is a placeholder the deployment replaces with the account id before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "docusign.templates.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "docusign-account.invalid"
      ],
      "endpoint": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/templates",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-docusign-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "docusign-account-templates",
      "description": "List the account's templates (optionally limited to a folder): names, ids and descriptions of reusable signing documents — internal contract tooling, classified as internal data.\n\nThe registered path covers the collection read only — single-template reads are not registered by this pack.\n\nACCOUNT_ID is a placeholder the deployment replaces before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "docusign.users.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "docusign-account.invalid"
      ],
      "endpoint": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/users",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-docusign-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "docusign-account-users",
      "description": "Retrieve the list of users for the account: names, email addresses and permission settings — employee personal data, classified as pii (personal data).\n\nThe registered path covers the collection read only — single-user reads are not registered by this pack.\n\nACCOUNT_ID is a placeholder the deployment replaces before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "docusign.envelopes.create_send",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "docusign-account.invalid"
      ],
      "endpoint": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/envelopes",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-docusign-oauth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "create",
        "send"
      ],
      "resource_id": "docusign-account-envelopes",
      "description": "Create an envelope and send it for signature in one call. The documented effect is delivery: with the request's status property set to 'sent' this single call both creates the envelope and sends it to the named recipients for legally binding electronic signature — recipients are notified, the signing process starts, and a delivered envelope cannot be un-delivered (voiding is a separate act that cancels an in-flight envelope but does not un-send the notification).\n\nThis is object-created and legally significant outbound transmission, not request-accepted, so the actions are create and send at the minimum R3 tier — send is one of the designated actions requiring human approval. The same endpoint with status 'created' saves a draft without sending; that does not lower the tier, because the registered capability covers the send.\n\nACCOUNT_ID is a placeholder the deployment replaces before enabling.\n\nOn supported AAES-mediated execution paths, the declared irreversible actions require an authorized person’s approval. Observation-only and bypass calls cannot be stopped by this control.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "docusign-account-envelopes",
      "kind": "api",
      "locator": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/envelopes",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "docusign-account-templates",
      "kind": "api",
      "locator": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/templates",
      "data_class": "internal",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "docusign-account-users",
      "kind": "api",
      "locator": "https://docusign-account.invalid/restapi/v2.1/accounts/ACCOUNT_ID/users",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-22",
    "sources": [
      "https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/ (retrieved 2026-09-21)",
      "https://raw.githubusercontent.com/docusign/OpenAPI-Specifications/master/esignature.rest.swagger-v2.1.json (retrieved 2026-09-21)",
      "https://developers.docusign.com/platform/auth/authcode/ (retrieved 2026-09-21)",
      "https://developers.docusign.com/platform/auth/jwt/ (retrieved 2026-09-21)",
      "https://developers.docusign.com/platform/auth/reference/user-info/ (retrieved 2026-09-21)",
      "https://www.docusign.com/blog/developers/authorization-code-grant-refresh-tokens (retrieved 2026-09-21)"
    ],
    "reviewer_id": "aaes-eng"
  }
}