Embedded Template Edit View: PUT .../documents/{documentId}/tabs returns 401 AUTHORIZATION_INVALID_TOKEN when UPDATING an existing prefill tab — but POST (add) works

Subject: Embedded Template Edit View: PUT .../documents/{documentId}/tabs returns 401 AUTHORIZATION_INVALID_TOKEN when UPDATING an existing prefill tab — but POST (add) works

Environment: eSignature REST API v2.1, Demo (account-d.docusign.com / demo.docusign.net, editor host apps-d.docusign.com).

Use case: We embed the Template Edit View in our web app (in an <iframe>) so users can tag/adjust fields on a template.

How we create the edit view (server side)

POST /restapi/v2.1/accounts/{accountId}/templates/{templateId}/views/edit
Authorization: Bearer <JWT-grant app token, scope: "signature impersonation">

{
  "returnUrl": "https://<our-return-page>",
  "viewAccess": "template",
  "frameAncestors": ["https://<our-app-origin>"],
  "settings": { "startingScreen": "Tagger" }
}

The returned url (a .../managed_token/v1/redeem?slt=... link) is set as the <iframe src>. The redeem redirects to apps-d.docusign.com/send/prepare-template/{templateId}/add-fields, and the embedded editor then uses a managed token for all its API calls.

The problem — what works vs. what fails, all in the same embedded session

• GET .../documents/1/tabs (load tabs) → 200 ✅
• POST .../templates/{id}/documents/1/tabs (ADD a prefill tab) → 201 ✅
• PUT .../templates/{id}/recipients/1/tabs (edit a RECIPIENT tab) → 200 ✅
• PUT .../templates/{id}/documents/1/tabs (MOVE/UPDATE an existing prefill/sender tab) → 401 ❌

The failing response:

{ "errorCode": "AUTHORIZATION_INVALID_TOKEN",
  "message": "The access token provided is expired, revoked or malformed." }

So with the same managed token, in the same session: adding a prefill tab (POST) works, but updating an existing one (PUT) fails with 401.

Network evidence — three calls to the SAME documents/1/tabs on the SAME template; only the token differs

(A) ADD prefill tab   POST .../documents/1/tabs   Bearer <managed token>   => 201  OK
    body: { prefillTabs: { textTabs: [ { new tab, no tabId } ] } }

(B) UPDATE prefill    PUT  .../documents/1/tabs   Bearer <managed token>   => 401  FAIL   (THE FAILURE)
    body: { prefillTabs: { textTabs: [ { tabId: <existing>, xPosition: 236, yPosition: 63 } ] } }

(C) UPDATE prefill    PUT  .../documents/1/tabs   Bearer <full session>    => 200  OK
    body: (byte-for-byte identical to B)

(B) and (C) are the identical request except the bearer token. (A) proves the managed token can write documents/1/tabs for create; only update (B) fails.

Token comparison (decoded claims; raw tokens omitted)

Managed edit-view token — the one that gets 401:

TokenType : 18
amr       : ["managed_token", "interactive"]
scp       : ["signature"]
mtclms    : Source "POSTTemplateEditView", ViewAccess 3, TemplateId <redacted>
(time-valid, not expired)

Full user session token — the SAME PUT succeeds with this (used when editing the same template directly on docusign.com):

TokenType : 5
amr       : ["refresh_token"]
scp       : [44 scopes incl. signature, account_read, settings_service_write, ...]

A JWT-grant app token (scope: signature impersonation) also returns 200 on the same PUT from our backend.

What we have ruled out

• Token expiry — the failing managed token is time-valid (often newer than tokens that succeed on other calls).
• Edit lock — the same lock token gave 200 on one call and 401 on another; lock problems return EDIT_LOCK_* errors, not AUTHORIZATION_INVALID_TOKEN.
• Request body — the identical body succeeds with a different token.
• Verb / endpoint scope — POST to the same endpoint succeeds with the managed token; only PUT (update existing) fails.

We also tried other viewAccess values: only template (ViewAccess 3) and envelope (ViewAccess 2) are accepted (templateReadonly / full → INVALID_REQUEST_BODY). In envelope mode the managed token is even more restricted — even GET .../documents/1/tabs returns 401.

Questions

1. Is the Template Edit View managed token (createEditView, viewAccess: template) intentionally not authorized to update existing document-level prefill (sender) tabs via PUT .../documents/{documentId}/tabs, while it is allowed to POST (create) them? If so, is this documented?
2. Is there a supported configuration (a viewAccess value, a settings.* flag, or a different embedded view) that lets embedded users reposition/edit existing prefill tabs?
3. If embedded prefill/sender-tab editing is unsupported, what is the recommended pattern — manage prefill-tab placement server-side with an account/JWT token, use a Sender/Correct view, or anchor-based placement?

Happy to share the account ID, template ID, full request/response, and a correlation/transaction ID of a specific failing call privately.