POST /v1/authorize

The second call of a signing session. Ask your provider for the signer’s approval of exactly the digests in the request, and return a reference to that approval. A qualified remote signature binds the approval to these digests, so they are final: no later call adds one.

Request

The common request fields, plus:

{
    "credential_id": "cred_7Qk...",
    "digests": [
        {
            "value": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
            "hash_algorithm_oid": "2.16.840.1.101.3.4.2.1",
            "label": "Service Agreement"
        }
    ]
}

Field	Description
credential_id	The credential.id your worker returned, or static for a static certificate.
digests	The complete digest set. SignatureAPI sends one digest today. Handle an array anyway.
digests[].value	The digest bytes, base64. What they hash depends on the signature format.
digests[].hash_algorithm_oid	The hash algorithm. SignatureAPI sends SHA-256 (2.16.840.1.101.3.4.2.1) today.
digests[].label	The envelope title, or Document when the envelope has none. Show it on any approval screen you host, so the signer knows what they approve.

When the request resumes after a redirect, it carries the same credential_id and digests, plus "callback": { "code": "..." }.

Response

{
    "status": "completed",
    "authorization": { "reference": "sad_3Fh...", "expires_at": "2026-08-24T16:50:00Z" }
}

Field	Required	Description
authorization.reference	Yes	Your handle on the approval. It is opaque to SignatureAPI, which only sends it back to sign.
authorization.expires_at	No	When the approval stops being usable.

The signer must approve first

Real signers usually act here: they approve with a PIN, a one-time password, their app or a hosted page. For a one-shot cms provider, the same interaction can also identify the signer and issue the certificate that sign returns. Answer pending and choose a channel:

• The signer approves on a page. Answer with an action_url, then send the browser to callback_url with a single-use code. SignatureAPI calls authorize again with that code.
• The signer approves in an app. Answer with poll_after. SignatureAPI calls authorize again with the same body after that many seconds. Answer each poll from your provider’s current state, and don’t send a new push notification on every poll.

You can offer both. See Pending steps for the rules and the deadline, and the recipes for complete examples.

If the signer refuses, answer failed with access_denied. The signer can retry from the ceremony.