Pending steps

Answer pending when the signer must do something at your provider before you can return a result, such as identify or approve. Only credential and authorize can answer pending. sign can’t.

{
    "status": "pending",
    "action_url": "https://signer.example.com/consent?ticket=...",
    "poll_after": 3,
    "expires_at": "2026-08-24T16:45:00Z"
}

A pending answer offers at least one way to finish the step: action_url, poll_after, or both.

Redirect: action_url

An absolute https URL. SignatureAPI sends the signer’s browser there. It can be your provider’s page or a page your worker hosts.

The step ends when the browser arrives at callback_url. Append one of these to it:

• code. An opaque, single-use value you mint. SignatureAPI calls the same operation again with "callback": { "code": "..." }, and you turn the code into a result.
• error, and optionally error_description. The session fails with that reason, and the signer can retry from the ceremony.

A request that carries callback.code must get completed or failed. Never answer it with pending.

Providers usually require an exact, pre-registered OAuth redirect URI. Register your worker’s own URI with the provider, finish the exchange in your worker, then redirect the browser to callback_url.

callback_url works once. A replayed callback takes the signer back to the ceremony and has no other effect.

Poll: poll_after

The number of seconds after which SignatureAPI calls the same operation again with the same body. SignatureAPI keeps the value between 1 and 60. Answer pending again, or resolve. Use this for app confirmations, QR codes and wallets, where the browser never comes back by itself.

A poll repeats the call, not the act. If your authorize sends a push notification, don’t send another one on every poll. Answer from your provider’s current state.

Deadline

The signer has until the connection’s Authorization timeout, 5 minutes by default, to finish a pending step. An expires_at on a pending answer can shorten that deadline, never extend it. After the deadline, the session fails, and the signer can retry from the ceremony.