---
title: "Embed a Ceremony in Vue and Nuxt"
description: "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."
canonical: "https://signatureapi.com/docs/embedded/frameworks/vue-nuxt"
source: "https://signatureapi.com/docs/embedded/frameworks/vue-nuxt.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:39:46Z"
---

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

_Last verified against API version 1.18.0._

This guide builds a `SigningCeremony` Vue component that shows the ceremony in an `<iframe>` and emits each [ceremony event](https://signatureapi.com/docs/embedded/ceremony-events). 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](https://signatureapi.com/docs/embedded/frameworks/react#create-the-ceremony-on-your-server).

The code is written for Vue 3.5 and Nuxt 4. `useTemplateRef` needs Vue 3.5 or later.

## Before you start

- An [API key](https://signatureapi.com/docs/api/authentication). Use a test key while you build: test envelopes are free and not legally binding.
- Your app's origin, such as `http://localhost:3000` for `nuxt dev`. The ceremony loads in an iframe only on the origins you list in `embeddable_in`.
- A way to read the signed-in user on the server. SignatureAPI receives that identity through [custom authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom).

The full request flow, with every call and event in order, is in [Embedding in a Web Application](https://signatureapi.com/docs/embedded/web-app).

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

```typescript nuxt.config.ts
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.

```typescript server/utils/signatureapi.ts
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:

```typescript server/api/signing-session.post.ts
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 };
});
```

```typescript server/api/signing-session/status.get.ts
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:

```typescript app/utils/ceremony.ts
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:

```html app/components/SigningCeremony.vue
<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:

```html app/pages/sign.vue
<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](https://signatureapi.com/docs/embedded/ceremony-events#event-types).

## Test it

1. Set `NUXT_SIGNATUREAPI_KEY` to a test key and run `nuxt dev`.
2. Open `/sign`, select **Sign the agreement**, sign the sample document and select **Finish**.
3. 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](https://signatureapi.com/docs/embedded/web-app#troubleshooting).

For work that must happen once, such as storing the signed PDF, use the [`recipient.completed`](https://signatureapi.com/docs/api/resources/events/recipient-events) webhook in a server route rather than the browser event.

## Keep learning

- [Ceremony Customization](https://signatureapi.com/docs/embedded/customization): accent color, Cancel button and result page delay.
- [Ceremony Events](https://signatureapi.com/docs/embedded/ceremony-events): every event and its `error_type` values.
- [Angular](https://signatureapi.com/docs/embedded/frameworks/angular) and [Svelte](https://signatureapi.com/docs/embedded/frameworks/svelte): the same component in other frameworks.
