Skip to content

Platforms

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.

This guide builds a standalone SigningCeremony Angular component that shows the ceremony in an <iframe> and emits each ceremony event 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. 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.

The full request flow, with every call and event in order, is in Embedding in a Web Application.

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.

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:

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.

Build the signing component

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

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:

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:

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.

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.

For work that must happen once, such as storing the signed PDF, use the recipient.completed webhook on your server rather than the browser event.

Keep learning