Standing authorisations

​

What it is

Some documents carry an organisation’s signature on every copy: salary adjustment letters, employment confirmations, the employer section of a benefit application. The usual workaround is to paste a picture of somebody’s signature into the PDF. That picture records nothing about who applied it or to which document, never expires, and outlives the person’s job. A standing authorisation is the record that replaces it. Once, an authorised person (the grantor) signs a short document, the mandate. It says that your organisation may apply their signature to documents it sends under one brand, for a stated period, and what that does and does not cover. The grantor needs no Vumasign account. They are identified by the mandate they signed, after entering a one-time code sent to their email address (signer verification).

​

How it works

1. You request it with POST /api/v1/standing-authorisations/invitations, using a key that names authorisations:invite. You name the brand, the legal entity the grantor signs for, the grantor, and how long it should last: at most 12 months. The request grants nothing. You receive authorisation.invited.
2. Vumasign sends the mandate. It is a Vumasign envelope, generated for this request and sent under your brand. Before it opens, the grantor must enter a one-time code sent to their email address. Every email the grantor receives about it names your organisation and the brand, not the member who created your key. Your members receive no email about it, and the mandate envelope does not appear among your envelopes, in the API or in the dashboard.
3. The grantor reads and signs it. The mandate says, in plain words, what they are agreeing to (below). They may correct their title, and may attach the board resolution or delegation that authorises them, as one PDF of at most 10 MB.
4. It becomes active when the signed mandate is sealed, normally within a minute or two of signing. Signing alone is not enough. You receive authorisation.granted, and the grantor receives an email confirming it, with a link to see where their signature has been applied and a link to revoke it.
5. It ends when it is revoked or reaches valid_until. From valid_until it reads expired, and you receive authorisation.expired. It records the brand’s name, email display name and logo as the grantor saw them: if the brand changes any of them, or is archived, before the signed mandate is sealed, it never takes effect and becomes invalidated.

​

What the grantor agrees to

This is the mandate’s wording, generated from the same source as the document the grantor signs. Values in brackets come from your request:

Standing authorisation SA-[number] I, [grantor], confirm that I am authorised to sign documents on behalf of [legal entity] in the capacity stated beside my signature, and to direct that my signature be applied as set out here. [your organisation] may apply my signature to any document it sends under the [brand] brand, when it chooses to. [your organisation] decides which documents those are, and is responsible for that decision. My signature will be applied, without my involvement, to each document [your organisation] chooses to send with this authority, at the moment it is sent. I will not review each document individually. How [your organisation] says it intends to use this authority (only if you give one): “[your description]”. This description is theirs. Vumasign does not check documents against it, and it does not limit this authority. This authority does not cover: witnessing any signature; choosing any answer or value in the part of a document I sign, because every value in that part is fixed by [your organisation] before the document is sent; any document not sent under the [brand] brand. Other people may complete their own parts of a document after my signature has been applied. From [the start, or the moment this mandate takes effect once signed] until [the end], unless revoked first. I may revoke it at any time, with immediate effect for documents not yet sent, using the link in the email confirming this authority and in every summary and notice about it. I will receive a weekly summary listing each document my signature was applied to, with its title and who applied it.

The grantor then signs, dates it, gives their name and “Your title or capacity”, and may fill in “Your authority to delegate (for example, a board resolution and its date)”. If you give an intended use, the mandate shows it in quotation marks as your description. Vumasign does not check documents against it, and it does not limit the authority.

​

Requesting one

The request’s fields are in the API reference. Its limits:

• Validity: valid_until must be after the start, at most 12 months after it, and at least 2 days from now. valid_from may be at most 90 days ahead. Leave it out and the authorisation runs from the moment it takes effect.
• The invite: the mandate lapses unsigned after 14 days, or 1 day before valid_until if that is sooner. You may set invite_expires_at between 1 and 30 days from now, and no later than 1 day before valid_until.
• The words you supply (the legal entity’s name and registration, the grantor’s name and title, and the intended use) must each be one line, with no links, no control characters and no “Vumasign”. The intended use also refuses a bare domain such as example.com. The brand’s name and your organisation’s name are held to the same rules, because the mandate prints them.
• Every refusal comes before anything is created. If the mandate is created but its send is refused, you get that refusal, the authorisation is left cancelled with cancellation.reason not_sent, and you receive authorisation.cancelled. A mandate that is still unsent 10 minutes after the request is cancelled the same way. So is one whose email to the grantor could not be delivered: that request answers service_unavailable, and the mandate’s link is withdrawn. Request again. If the grantor reports no email, resend the request.

authorisations:invite and authorisations:apply are explicit-only: a full-access key does not hold them. An owner or admin gives a key either one when creating it, under Settings → API keys, once standing authorisations are switched on for that kind of key.

​

Cancelling and resending

While a request is invited and the grantor has not signed:

• POST /api/v1/standing-authorisations/{id}/cancel withdraws it. The mandate link stops working, the grantor is told, and the status becomes cancelled. Once the grantor has signed, it can no longer be cancelled: wait for authorisation.granted, then revoke it.
• POST /api/v1/standing-authorisations/{id}/resend emails the grantor a fresh link; the previous one stops working. At most 3 times in 1 day. If the email cannot be delivered, the answer is service_unavailable rather than a success, because the previous link has already stopped working: send the same request again. A resend that was not delivered does not count towards that limit, but no more than 10 are attempted in 1 day. To change the grantor’s address, cancel and request again.

Both need authorisations:invite.

​

Reading

GET /api/v1/standing-authorisations lists them, filtered by status, brand_id or your reference, and GET /api/v1/standing-authorisations/{id} reads one. Both need authorisations:read. Neither returns the signature, the mandate document or anything from the grant’s verification.

​

Revoking

POST /api/v1/standing-authorisations/{id}/revoke, with authorisations:revoke and a reason, revokes an active authorisation with immediate effect for documents not yet sent. Revoking it again returns it unchanged. An invited request is cancelled instead. The grantor can revoke it too, from the link in the email confirming it. Revocation is recorded on the authorisation itself.

​

Sandbox and live

A request made with a vsk_test_ key creates a sandbox authorisation: its mandate is watermarked and binds nobody. Because a test key emails only verified test recipients and verified members of your organisation, the grantor’s address must be one of those. A test key lists, reads, cancels, resends and revokes only sandbox authorisations: a live one answers not_found to it. A vsk_live_ key sees both, as it sees sandbox and live envelopes alike; each authorisation says which it is in sandbox. See test keys and live keys.

​

Webhooks

Each authorisation event carries authorisation_id, the authorisation’s brand_id and sandbox, a uri to re-read it, and envelope_id: null. You receive no envelope.* events for the mandate envelope itself. See webhooks for the body and how to verify it.

​

Related

Signer verification (the email code the grantor enters) · Brands · Test keys and live keys · Webhooks