> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Standing authorisations

> Ask an authorised person to sign a mandate once, so that your organisation's authority to use their signature under one brand is on record.

export const testKeyPrefix = "vsk_test_";

export const scopeAuthorisationsRevoke = "authorisations:revoke";

export const scopeAuthorisationsRead = "authorisations:read";

export const scopeAuthorisationsInvite = "authorisations:invite";

export const scopeAuthorisationsApply = "authorisations:apply";

export const saValidUntilMinDays = "2";

export const saValidFromMaxDays = "90";

export const saStatusInvited = "invited";

export const saStatusInvalidated = "invalidated";

export const saStatusExpired = "expired";

export const saStatusCancelled = "cancelled";

export const saStatusActive = "active";

export const saResendWindow = "1 day";

export const saResendLimit = "3";

export const saResendAttemptLimit = "10";

export const saNotSentAfter = "10 minutes";

export const saNotFoundCode = "not_found";

export const saNotEnabledCode = "standing_authorisations_not_enabled";

export const saNotDeliveredCode = "service_unavailable";

export const saMaxValidityMonths = "12";

export const saInviteMinDays = "1";

export const saInviteMaxDays = "30";

export const saInviteDefaultDays = "14";

export const saInviteBeforeEnd = "1 day";

export const saCancelNotSent = "not_sent";

export const saAuthorityMaxSize = "10 MB";

export const liveKeyPrefix = "vsk_live_";

export const eventAuthorisationInvited = "authorisation.invited";

export const eventAuthorisationGranted = "authorisation.granted";

export const eventAuthorisationExpired = "authorisation.expired";

export const eventAuthorisationCancelled = "authorisation.cancelled";

<Note>
  Standing authorisations are switched on by Vumasign, per organisation and separately for sandbox and live.
  Until then every request answers <code>{saNotEnabledCode}</code>. This release covers requesting,
  granting, reading, cancelling and revoking an authorisation. Applying one to a document comes in a later
  release.
</Note>

## 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](/concepts/signer-verification)).

## How it works

1. **You request it** with `POST /api/v1/standing-authorisations/invitations`, using a key that names
   <code>{scopeAuthorisationsInvite}</code>. You name the brand, the legal entity the grantor signs for, the
   grantor, and how long it should last: at most {saMaxValidityMonths} months. **The request grants
   nothing.** You receive <code>{eventAuthorisationInvited}</code>.
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 {saAuthorityMaxSize}.
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 <code>{eventAuthorisationGranted}</code>, 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
   <code>{saStatusExpired}</code>, and you receive <code>{eventAuthorisationExpired}</code>. 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 <code>{saStatusInvalidated}</code>.

| Status | What it means |
| - | - |
| `invited` | Requested. The mandate has been sent to the grantor and grants nothing yet. |
| `active` | The grantor signed the mandate and it was sealed. It is in force until it ends. |
| `declined` | The grantor declined the mandate. |
| `expired_unsigned` | The mandate lapsed unsigned. |
| `cancelled` | The request ended without a grant: see `cancellation.reason`. |
| `revoked` | It was in force and was revoked: by you, by an owner or admin, or by the grantor. |
| `expired` | It was in force and reached `valid_until`. |
| `invalidated` | The brand it names changed its name, email display name or logo, or was archived. |

## 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](/api-reference/invite-standing-authorisation). Its limits:

* **Validity:** `valid_until` must be after the start, at most {saMaxValidityMonths} months after it, and
  at least {saValidUntilMinDays} days from now. `valid_from` may be at most {saValidFromMaxDays} days ahead.
  Leave it out and the authorisation runs from the moment it takes effect.
* **The invite:** the mandate lapses unsigned after {saInviteDefaultDays} days, or {saInviteBeforeEnd} before
  `valid_until` if that is sooner. You may set `invite_expires_at` between {saInviteMinDays} and
  {saInviteMaxDays} days from now, and no later than {saInviteBeforeEnd} 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 <code>{saStatusCancelled}</code> with `cancellation.reason`
  <code>{saCancelNotSent}</code>, and you
  receive <code>{eventAuthorisationCancelled}</code>. A mandate that is still unsent {saNotSentAfter} after the
  request is cancelled the same way. So is one whose email to the grantor could not be delivered: that
  request answers <code>{saNotDeliveredCode}</code>, and the mandate's link is withdrawn. Request again.
  If the grantor reports no email, resend the request.

<code>{scopeAuthorisationsInvite}</code> and <code>{scopeAuthorisationsApply}</code> 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 <code>{saStatusInvited}</code> 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 <code>{saStatusCancelled}</code>. Once the grantor has signed, it can no longer be
  cancelled: wait for <code>{eventAuthorisationGranted}</code>, then revoke it.
* `POST /api/v1/standing-authorisations/{id}/resend` emails the grantor a fresh link; the previous one
  stops working. At most {saResendLimit} times in {saResendWindow}. If the email cannot be delivered, the
  answer is <code>{saNotDeliveredCode}</code> 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 {saResendAttemptLimit} are attempted in {saResendWindow}. To change the grantor's address, cancel and request again.

Both need <code>{scopeAuthorisationsInvite}</code>.

## 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 <code>{scopeAuthorisationsRead}</code>. Neither
returns the signature, the mandate document or anything from the grant's verification.

## Revoking

`POST /api/v1/standing-authorisations/{id}/revoke`, with <code>{scopeAuthorisationsRevoke}</code> and a
`reason`, revokes an <code>{saStatusActive}</code> authorisation with immediate effect for documents not yet
sent. Revoking it again returns it unchanged. An <code>{saStatusInvited}</code> 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 <code>{testKeyPrefix}</code> 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 <code>{saNotFoundCode}</code> to it. A <code>{liveKeyPrefix}</code> 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](/concepts/test-and-live).

## 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.

| Event | What happened |
| - | - |
| `authorisation.invited` | A standing authorisation was requested: the request was accepted and its mandate is being sent to the grantor in the same call. If that send is refused, `authorisation.cancelled` follows with `cancellation.reason` `not_sent`. `authorisation_id` says which; `envelope_id` is null, because the mandate envelope is never published. |
| `authorisation.granted` | The grantor signed the mandate AND it was sealed: the authorisation is now `active`. Normally a minute or two after signing. ⚠️ NOTHING FIRES AT SIGNING ITSELF — the grant takes effect at the seal, so do not treat a signature you heard about elsewhere as a grant. |
| `authorisation.declined` | The grantor declined the mandate. The authorisation is `declined` and never takes effect. |
| `authorisation.invite_expired` | The mandate lapsed unsigned at `invite_expires_at`. The authorisation is `expired_unsigned`. |
| `authorisation.cancelled` | The request ended without a grant: you or a member cancelled it, its mandate could not be sent or sealed, it was not signed by the person named, the capacity they signed with cannot be printed, it sealed only after `valid_until`, or activation failed. Read `cancellation.reason` on the resource. |
| `authorisation.revoked` | An `active` authorisation was revoked: by your key, by an owner or admin, or by the grantor. |
| `authorisation.invalidated` | The brand the authorisation was granted under changed its name, email display name or logo, or was archived. The authorisation can no longer be applied; request a new one. |
| `authorisation.expired` | An `active` authorisation reached `valid_until` and has ended. It reads `expired` from that moment, and this event follows within minutes. Request a new one to continue. |

See [webhooks](/guides/webhooks) for the body and how to verify it.

## Related

[Signer verification](/concepts/signer-verification) (the email code the grantor enters) ·
[Brands](/concepts/brands) · [Test keys and live keys](/concepts/test-and-live) · [Webhooks](/guides/webhooks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.