Reissue signing link

Outcome

Revoke an open unsigned recipient link, issue its replacement and queue a new request. Verify retained delivery and Notify dispatch state separately from link creation.

Before you start

• Verify the environment, authenticated identity and specifically approved organization context.
• The published application permission is workspace:write. Resolve and bind the exact canonical Sign workspace. A supplied id or organization membership alone grants no workspace access.
• Session callers require read_write or admin workspace access. API-key resource binding is verified by Auth; never treat a caller-supplied header as an independent grant.
• Approve the documented mutation and actual recipient/document targets before CLI --confirm or MCP confirm:true. A synthetic fixture authorizes no live agreement, notification or data deletion.

Discover the target

topolo whoami --json
topolo actions get app_topolo_sign.envelopes.recipients.reissue --detail --json
topolo resources topolo-sign --json
topolo workspaces list topolo-sign --json

• Set SIGN_WORKSPACE_ID to the exact granted workspace returned by discovery.
• Resolve envelopeId through envelopes.list/get or retain the exact creation response.
• Read envelope.recipients and retain the exact recipient id. A signer email is not recipientId.

Request

POST /api/envelopes/{envelopeId}/recipients/{recipientId}/reissue

Inspect and test this action. Save the reviewed input as payload.json. Supply resource context separately.

Input fields

Read the complete input schema.

Effects

• Revokes one unsigned recipient's current signing link: the old URL answers 410 signing_token_revoked from then on.
• Issues a new signing link, returns it in $.signingLink and emails it to the recipient through Topolo Notify (held until their turn if earlier signers are still outstanding).
• Never changes anything already signed, the frozen source, or the envelope status. Records recipient.link_reissued in the audit trail.

Interpret the response

Read $.signingLink.recipientId for the returned envelope_recipient identifier. An empty collection does not discover a target.

Expect 200 with $.signingLink.signingUrl. Call envelopes.get and confirm the recipient's delivery in $.envelope.deliveries is queued, held or accepted.

Inspect the success schema. CLI/MCP add their transport envelope; --detail requests the full CLI result. HTTP 204 contains no JSON payload.

Worked examples

Captured from the exported Sign Worker with the existing SQLite-backed D1 harness applying all core, envelope and audit migrations to one local database, in-memory R2 and synthetic Auth/workspace/archive/Notify transports. These examples prove local validation, persistence and artifact production. They do not prove separate deployed D1 topology, real recipient consent, provider delivery or a live signed agreement. All identities, signing links and documents are synthetic; replace identifiers through authorized discovery and never execute a fixture against a live organization. Binary download examples use the released SDK binary projection; tests Base64-decode and compare original bytes, lengths and server SHA-256 headers.

Supported request · Revoke the previous bearer link and issue a synthetic replacement

Input · payload.json:

{
  "envelopeId": "b0db0353-6d5a-4a9b-b3f4-85f439ec4953",
  "recipientId": "843e8126-a83e-471e-bc54-e57c07c0067d"
}

CLI:

topolo actions validate app_topolo_sign.envelopes.recipients.reissue --data @payload.json --json
topolo actions plan app_topolo_sign.envelopes.recipients.reissue --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_sign.envelopes.recipients.reissue --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_sign.envelopes.recipients.reissue",
    "input": {
      "envelopeId": "b0db0353-6d5a-4a9b-b3f4-85f439ec4953",
      "recipientId": "843e8126-a83e-471e-bc54-e57c07c0067d"
    },
    "resourceType": "workspace",
    "resourceId": "<exact granted id from discovery>",
    "confirm": true,
    "detail": true
  }
}

Captured exported Worker response · HTTP 200:

{
  "signingLink": {
    "recipientId": "843e8126-a83e-471e-bc54-e57c07c0067d",
    "email": "recipient@example.test",
    "routingOrder": 1,
    "signingUrl": "https://sign.fixture.test/sign/339245822330cceba13826d89705dd20de272a24bdaf9eb83f2f9b5dd28f1641"
  }
}

HTTP 200. Expect 200 with $.signingLink.signingUrl. Call envelopes.get and confirm the recipient's delivery in $.envelope.deliveries is queued, held or accepted.

Refused request · HTTP 401

Input · payload.json:

{
  "envelopeId": "ed22fca5-d5f0-4392-8e71-96e247bf3875",
  "recipientId": "21ce3658-a6fa-407d-b236-5ec64fa4254f"
}

CLI:

topolo actions validate app_topolo_sign.envelopes.recipients.reissue --data @payload.json --json
topolo actions plan app_topolo_sign.envelopes.recipients.reissue --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json

Captured exported Worker response · HTTP 401:

{
  "error": "Token validation failed"
}

HTTP 401. Resolve the exact refusal before retrying. This request is not a successful workflow.

Refused request · HTTP 403

Input · payload.json:

{
  "envelopeId": "ed22fca5-d5f0-4392-8e71-96e247bf3875",
  "recipientId": "21ce3658-a6fa-407d-b236-5ec64fa4254f"
}

CLI:

topolo actions validate app_topolo_sign.envelopes.recipients.reissue --data @payload.json --json
topolo actions plan app_topolo_sign.envelopes.recipients.reissue --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json

Captured exported Worker response · HTTP 403:

{
  "error": "This workspace requires read_write access",
  "code": "workspace_access_insufficient"
}

HTTP 403. Resolve the exact refusal before retrying. This request is not a successful workflow.

Verify the result

• Expect 200 with $.signingLink.signingUrl.
• Call envelopes.get and confirm the recipient's delivery in $.envelope.deliveries is queued, held or accepted.

Errors and recovery

• envelope_not_found (HTTP 404): No envelope in this workspace carries that id. Call envelopes.list and use an id from the response.
• recipient_not_found (HTTP 404): The envelope has no recipient with that id. Call envelopes.get and use an id from $.envelope.recipients.
• envelope_not_open (HTTP 409): Only a sent or viewed envelope has live links. A draft is sent with envelopes.send; a completed, voided or declined envelope cannot be reopened.
• recipient_not_open (HTTP 409): The recipient has already signed or declined, so there is no link to reissue.
• forbidden (HTTP 403): Reissuing needs workspace:write in this workspace.
• auth_error (HTTP 401): Reauthenticate in the same approved context before retrying.
• workspace_access_insufficient (HTTP 403): Discover the actual workspace grant and obtain the documented required access; do not retry with a guessed workspace or broader organization.

Some existing refusals return a human message as error rather than a stable code; preserve the actual response, status and request id. Platform validation, authentication and resource checks can refuse before the handler.

Recovery boundary

A revoked link cannot be restored; reissue again to issue another.

Related actions

• Get Sign envelope: Get one signature envelope with its document, field schema, recipients and their individual signing status, and the delivery record for every party message ($.envelope.deliveries: signing requests and completed copies, with Notify dispatch outcome).

Evidence

Captured from the exported Sign Worker with the existing SQLite-backed D1 harness applying all core, envelope and audit migrations to one local database, in-memory R2 and synthetic Auth/workspace/archive/Notify transports. These examples prove local validation, persistence and artifact production. They do not prove separate deployed D1 topology, real recipient consent, provider delivery or a live signed agreement. All identities, signing links and documents are synthetic; replace identifiers through authorized discovery and never execute a fixture against a live organization. Binary download examples use the released SDK binary projection; tests Base64-decode and compare original bytes, lengths and server SHA-256 headers.