Platforms
Embed a Ceremony in Vue and Nuxt
Embed the signing ceremony in a Vue or Nuxt app with an iframe component that emits ceremony events, and a Nuxt server route that creates the ceremony.
This guide builds a SigningCeremony Vue component that shows the ceremony in an <iframe> and emits each ceremony event. In Nuxt, a server route creates the envelope with your API key. In a Vue app without Nuxt, any backend can play that role: see the Express routes in the React guide.
The code is written for Vue 3.5 and Nuxt 4. useTemplateRef needs Vue 3.5 or later.
Before you start
- An API key. Use a test key while you build: test envelopes are free and not legally binding.
- Your app’s origin, such as
http://localhost:3000fornuxt dev. The ceremony loads in an iframe only on the origins you list inembeddable_in. - A way to read the signed-in user on the server. SignatureAPI receives that identity through custom authentication.
The full request flow, with every call and event in order, is in Embedding in a Web Application.
Configure the server keys
Declare both values as private runtime config. Nuxt fills them from NUXT_SIGNATUREAPI_KEY and NUXT_SIGNING_ORIGIN at runtime and never sends them to the browser:
export default defineNuxtConfig({
runtimeConfig: {
signatureapiKey: '', // NUXT_SIGNATUREAPI_KEY
signingOrigin: 'http://localhost:3000', // NUXT_SIGNING_ORIGIN
},
});Call SignatureAPI from server code
Files in server/utils/ are auto-imported in Nuxt server code. createSigningSession creates the envelope, waits until it is in_progress (the ceremony doesn’t open before that) and returns the signer’s ceremony URL. hasSigned reads the envelope to confirm the result.
const API = 'https://api.signatureapi.com/v1';
interface Envelope {
id: string;
status: 'processing' | 'in_progress' | 'completed' | 'failed' | 'canceled';
recipients: Array<{ status: string; ceremony: { url: string | null } }>;
}
async function request(apiKey: string, path: string, init: RequestInit = {}): Promise<Envelope> {
const response = await fetch(`${API}${path}`, {
...init,
headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
});
if (!response.ok) throw new Error(`SignatureAPI ${path} returned ${response.status}`);
return (await response.json()) as Envelope;
}
/** Creates an envelope for one signer and returns the URL of their ceremony. */
export async function createSigningSession(options: {
apiKey: string;
origin: string; // the origin of the page that shows the iframe
signer: { id: string; name: string; email: string };
}) {
const { apiKey, origin, signer } = options;
let envelope = await request(apiKey, '/envelopes', {
method: 'POST',
body: JSON.stringify({
title: 'Service Agreement',
documents: [
{
url: 'https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf',
format: 'pdf',
places: [{ key: 'signer_signs_here', type: 'signature', recipient_key: 'client' }],
},
],
recipients: [
{
type: 'signer',
key: 'client',
name: signer.name,
email: signer.email,
ceremony: {
authentication: [{ type: 'custom', provider: 'Acme Portal', data: { user_id: signer.id } }],
embeddable_in: [origin],
},
},
],
}),
});
// The ceremony opens only once the envelope leaves `processing`.
for (let attempt = 0; envelope.status === 'processing' && attempt < 30; attempt++) {
await new Promise((resolve) => setTimeout(resolve, 1000));
envelope = await request(apiKey, `/envelopes/${envelope.id}`);
}
const url = envelope.recipients[0]?.ceremony.url;
if (envelope.status !== 'in_progress' || !url) {
throw new Error(`Envelope ${envelope.id} is ${envelope.status}`);
}
return { envelopeId: envelope.id, url };
}
/** Reads the envelope: true when the signer has completed their ceremony. */
export async function hasSigned(options: { apiKey: string; envelopeId: string }) {
const envelope = await request(options.apiKey, `/envelopes/${options.envelopeId}`);
return envelope.recipients[0]?.status === 'completed';
}Create the ceremony in a server route
Two routes act for the signed-in user only. The envelope id stays on the server:
export default defineEventHandler(async (event) => {
const user = await requireSignedInUser(event); // your auth, in server/utils
const config = useRuntimeConfig(event);
const session = await createSigningSession({
apiKey: config.signatureapiKey,
origin: config.signingOrigin,
signer: user,
});
await saveEnvelopeId(user.id, session.envelopeId); // your storage
return { url: session.url };
});export default defineEventHandler(async (event) => {
const user = await requireSignedInUser(event);
const config = useRuntimeConfig(event);
const envelopeId = await findEnvelopeId(user.id);
const signed = envelopeId ? await hasSigned({ apiKey: config.signatureapiKey, envelopeId }) : false;
return { signed };
});requireSignedInUser, saveEnvelopeId and findEnvelopeId stand for your own authentication and database helpers.
Build the signing component
Keep the event types and the URL helper in their own module:
export const CEREMONY_ORIGIN = 'https://sign.signatureapi.com';
export interface CeremonyEvent {
type: 'ceremony.completed' | 'ceremony.canceled' | 'ceremony.declined' | 'ceremony.failed';
error_type?: string; // only on ceremony.failed
error_message?: string; // only on ceremony.failed, for your logs
}
/** Adds the query parameters an iframe ceremony needs. */
export function embeddedUrl(url: string): string {
const embedded = new URL(url);
embedded.searchParams.set('embedded', 'true');
embedded.searchParams.set('event_delivery', 'message');
return embedded.toString();
}SigningCeremony shows the ceremony and emits a ceremony event for each message. It accepts a message only when it comes from https://sign.signatureapi.com and from its own iframe. It adds the listener in onMounted, so it is safe with server-side rendering:
<script setup lang="ts">
import { computed, onBeforeUnmount, onMounted, useTemplateRef } from 'vue';
import { CEREMONY_ORIGIN, embeddedUrl, type CeremonyEvent } from '~/utils/ceremony';
const props = defineProps<{ url: string }>();
const emit = defineEmits<{ ceremony: [event: CeremonyEvent] }>();
const iframe = useTemplateRef<HTMLIFrameElement>('iframe');
const src = computed(() => embeddedUrl(props.url));
function onMessage(event: MessageEvent) {
if (event.origin !== CEREMONY_ORIGIN) return;
if (event.source !== iframe.value?.contentWindow) return;
emit('ceremony', event.data as CeremonyEvent);
}
onMounted(() => window.addEventListener('message', onMessage));
onBeforeUnmount(() => window.removeEventListener('message', onMessage));
</script>
<template>
<iframe ref="iframe" :src="src" title="Sign the document" class="ceremony" />
</template>
<style scoped>
.ceremony {
width: 100%;
height: 80vh;
border: 0;
}
</style>In a Vue app without Nuxt, import ceremony.ts with a relative path instead of ~/utils/.
Handle the events and redirect
The page asks the server route for a ceremony URL and reacts to each event. On ceremony.completed it confirms the result on the server before it navigates:
<script setup lang="ts">
import type { CeremonyEvent } from '~/utils/ceremony';
const url = ref<string | null>(null);
const message = ref<string | null>(null);
async function start() {
message.value = null;
try {
const session = await $fetch('/api/signing-session', { method: 'POST' });
url.value = session.url;
} catch {
message.value = 'We could not start the signing session.';
}
}
async function onCeremony(event: CeremonyEvent) {
switch (event.type) {
case 'ceremony.completed': {
// The message comes from the browser: confirm on the server first.
const { signed } = await $fetch('/api/signing-session/status');
if (signed) await navigateTo('/sign/done');
else message.value = 'We are still processing your signature.';
break;
}
case 'ceremony.canceled':
url.value = null;
break;
case 'ceremony.declined':
await navigateTo('/sign/declined');
break;
case 'ceremony.failed':
console.error('Ceremony failed:', event.error_type, event.error_message);
url.value = null;
message.value = 'This signing link no longer works. Start again to get a new one.';
break;
}
}
</script>
<template>
<SigningCeremony v-if="url" :url="url" @ceremony="onCeremony" />
<div v-else>
<p v-if="message" role="alert">{{ message }}</p>
<button type="button" @click="start">Sign the agreement</button>
</div>
</template>In a Vue app with Vue Router, replace $fetch with fetch and navigateTo with router.push.
The ceremony shows its own result page for 3 seconds before it sends ceremony.completed. To navigate right away, set redirect_delay to 0 in the recipient’s ceremony. See Event types.
Test it
- Set
NUXT_SIGNATUREAPI_KEYto a test key and runnuxt dev. - Open
/sign, select Sign the agreement, sign the sample document and select Finish. - After the result page, the app navigates to
/sign/done.
If the iframe stays blank and the console reports a frame-ancestors error, signingOrigin doesn’t match the page’s origin. See Troubleshooting.
For work that must happen once, such as storing the signed PDF, use the recipient.completed webhook in a server route rather than the browser event.
Keep learning
- Ceremony Customization: accent color, Cancel button and result page delay.
- Ceremony Events: every event and its
error_typevalues. - Angular and Svelte: the same component in other frameworks.