---
title: "Embed a Ceremony in Angular"
description: "Embed the signing ceremony in an Angular app with a standalone iframe component that uses signal inputs and outputs, and confirm the result on your server."
canonical: "https://signatureapi.com/docs/embedded/frameworks/angular"
source: "https://signatureapi.com/docs/embedded/frameworks/angular.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:39:46Z"
---

# Embed a Ceremony in Angular

Embed the signing ceremony in an Angular app with a standalone iframe component that uses signal inputs and outputs, and confirm the result on your server.

_Last verified against API version 1.18.0._

This guide builds a standalone `SigningCeremony` Angular component that shows the ceremony in an `<iframe>` and emits each [ceremony event](https://signatureapi.com/docs/embedded/ceremony-events) through a signal output. Your backend creates the envelope, because the API key must never reach the browser.

The code is written for Angular 20 with standalone components, signals and the built-in control flow. It also works on Angular 19.

## 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:4200` for `ng serve`. The ceremony loads in an iframe only on the origins you list in `embeddable_in`.
- A backend that knows the signed-in user. 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).

## Create the ceremony on your server

Put the SignatureAPI calls in one server module. `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/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';
}
```

Expose two routes for the signed-in user. This example uses Express, which also runs the server of an Angular SSR app; any backend works:

```typescript server/routes.ts
import express from 'express';
import { createSigningSession, hasSigned } from './signatureapi';
import { requireUser, saveEnvelopeId, findEnvelopeId } from './your-app'; // your auth and storage

export const signingRoutes = express.Router();
const apiKey = process.env.SIGNATUREAPI_KEY ?? '';
const origin = process.env.APP_ORIGIN ?? 'http://localhost:4200';

signingRoutes.post('/api/signing-session', requireUser, async (req, res) => {
  const session = await createSigningSession({ apiKey, origin, signer: req.user });
  await saveEnvelopeId(req.user.id, session.envelopeId);
  res.json({ url: session.url });
});

signingRoutes.get('/api/signing-session/status', requireUser, async (req, res) => {
  const envelopeId = await findEnvelopeId(req.user.id);
  res.json({ signed: envelopeId ? await hasSigned({ apiKey, envelopeId }) : false });
});
```

`requireUser`, `saveEnvelopeId` and `findEnvelopeId` stand for your own authentication middleware and database. During `ng serve`, forward `/api` to this server with a [proxy configuration](https://angular.dev/tools/cli/serve#proxying-to-a-backend-server).

## Build the signing component

Keep the event types and the URL helper in their own file:

```typescript src/app/signing/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();
}
```

Angular blocks a plain string in an iframe's `src`, so the component marks the ceremony URL as a trusted resource URL with `DomSanitizer`. Pass it only URLs that come from your server. The component listens to `window` messages through its `host` metadata and accepts a message only when it comes from `https://sign.signatureapi.com` and from its own iframe:

```typescript src/app/signing/signing-ceremony.ts
import { Component, ElementRef, computed, inject, input, output, viewChild } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { CEREMONY_ORIGIN, embeddedUrl, type CeremonyEvent } from './ceremony';

@Component({
  selector: 'app-signing-ceremony',
  template: `<iframe #frame [src]="src()" title="Sign the document"></iframe>`,
  styles: `
    iframe {
      width: 100%;
      height: 80vh;
      border: 0;
    }
  `,
  host: { '(window:message)': 'onMessage($event)' },
})
export class SigningCeremony {
  readonly url = input.required<string>();
  readonly ceremonyEvent = output<CeremonyEvent>();

  private readonly frame = viewChild.required<ElementRef<HTMLIFrameElement>>('frame');
  private readonly sanitizer = inject(DomSanitizer);

  // The URL comes from your server; never pass user input here.
  protected readonly src = computed(() => this.sanitizer.bypassSecurityTrustResourceUrl(embeddedUrl(this.url())));

  protected onMessage(event: MessageEvent) {
    if (event.origin !== CEREMONY_ORIGIN) return;
    if (event.source !== this.frame().nativeElement.contentWindow) return;
    this.ceremonyEvent.emit(event.data as CeremonyEvent);
  }
}
```

## Handle the events and redirect

The page asks your server for a ceremony URL and reacts to each event. On `ceremony.completed` it confirms the result on the server before it navigates. It needs `provideHttpClient()` and `provideRouter()` in your application config:

```typescript src/app/signing/sign-agreement-page.ts
import { Component, inject, signal } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Router } from '@angular/router';
import { firstValueFrom } from 'rxjs';
import { SigningCeremony } from './signing-ceremony';
import type { CeremonyEvent } from './ceremony';

@Component({
  selector: 'app-sign-agreement-page',
  imports: [SigningCeremony],
  template: `
    @if (url(); as ceremonyUrl) {
      <app-signing-ceremony [url]="ceremonyUrl" (ceremonyEvent)="onCeremonyEvent($event)" />
    } @else {
      @if (message(); as text) {
        <p role="alert">{{ text }}</p>
      }
      <button type="button" (click)="start()" [disabled]="pending()">Sign the agreement</button>
    }
  `,
})
export class SignAgreementPage {
  private readonly http = inject(HttpClient);
  private readonly router = inject(Router);

  protected readonly url = signal<string | null>(null);
  protected readonly message = signal<string | null>(null);
  protected readonly pending = signal(false);

  protected async start() {
    this.pending.set(true);
    this.message.set(null);
    try {
      const session = await firstValueFrom(this.http.post<{ url: string }>('/api/signing-session', {}));
      this.url.set(session.url);
    } catch {
      this.message.set('We could not start the signing session.');
    } finally {
      this.pending.set(false);
    }
  }

  protected async onCeremonyEvent(event: CeremonyEvent) {
    switch (event.type) {
      case 'ceremony.completed': {
        // The message comes from the browser: confirm on the server first.
        const { signed } = await firstValueFrom(this.http.get<{ signed: boolean }>('/api/signing-session/status'));
        if (signed) await this.router.navigateByUrl('/agreements/signed');
        else this.message.set('We are still processing your signature.');
        break;
      }
      case 'ceremony.canceled':
        this.url.set(null);
        break;
      case 'ceremony.declined':
        await this.router.navigateByUrl('/agreements/declined');
        break;
      case 'ceremony.failed':
        console.error('Ceremony failed:', event.error_type, event.error_message);
        this.url.set(null);
        this.message.set('This signing link no longer works. Start again to get a new one.');
        break;
    }
  }
}
```

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. Run your server with a test key in `SIGNATUREAPI_KEY` and `http://localhost:4200` in `APP_ORIGIN`, then run `ng serve`.
2. Open the page, select **Sign the agreement**, sign the sample document and select **Finish**.
3. After the result page, the app navigates to `/agreements/signed`.

If the iframe stays blank and the console reports a `frame-ancestors` error, `APP_ORIGIN` 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 on your server 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.
- [Vue and Nuxt](https://signatureapi.com/docs/embedded/frameworks/vue-nuxt) and [Svelte](https://signatureapi.com/docs/embedded/frameworks/svelte): the same component in other frameworks.
