API og MCP

Send dokumenter til underskrift med MitID, BankID eller tegnet underskrift direkte fra jeres egne systemer, eller lad en AI-assistent som Claude gøre det for jer.

API'et og MCP-serveren kan det samme som Forsegl-appen. De bruger de samme regler, rettigheder og den samme API-nøgle, så det, I bygger med det ene, virker også med det andet.

API-nøgler

Opret en nøgle i appen under API og MCP. Nøglen starter med fsg_ og vises kun én gang, så gem den et sikkert sted, f.eks. i en password manager eller jeres secrets-håndtering.

Send nøglen i Authorization-headeren på hver forespørgsel:

Authorization: Bearer fsg_…

• En nøgle handler på vegne af den bruger, der oprettede den. Sager, den opretter, får brugeren som afsender.
• Nøglen har adgang til hele organisationens sager, mapper, brands og webhooks.
• Nøglen kan ikke ændre adgangskoder eller oprette og tilbagekalde andre nøgler. Det kræver, at man er logget ind i appen.
• Tilbagekald en nøgle i appen, så holder den op med at virke med det samme. Brug én nøgle pr. integration eller person.

Hurtigstart

Fire kald fra kladde til sendt sag. Underskriverne får en mail med et personligt link.

# 1. Opret en sag
curl https://app.forsegl.dk/api/v1/cases \
  -H "Authorization: Bearer $FORSEGL_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Lejekontrakt, Vesterbrogade 14"}'
# → {"id": "6f1c…", "reference": "SG-00042", "status": "draft", …}

# 2. Tilføj en PDF (base64 eller en offentlig https-adresse)
curl https://app.forsegl.dk/api/v1/cases/6f1c…/documents \
  -H "Authorization: Bearer $FORSEGL_KEY" -H "Content-Type: application/json" \
  -d '{"documents": [{"name": "Lejekontrakt.pdf", "url": "https://example.com/lejekontrakt.pdf"}]}'

# 3. Tilføj underskrivere
curl -X PUT https://app.forsegl.dk/api/v1/cases/6f1c…/signers \
  -H "Authorization: Bearer $FORSEGL_KEY" -H "Content-Type: application/json" \
  -d '{"signers": [{"name": "Anna Holm", "email": "anna@example.com"},
                   {"name": "Bo Lund", "email": "bo@example.com", "role": "copy"}]}'

# 4. Send til underskrift
curl -X POST https://app.forsegl.dk/api/v1/cases/6f1c…/send \
  -H "Authorization: Bearer $FORSEGL_KEY"

Følg sagen med GET /cases/{id} eller en webhook. Når status er completed, henter I den underskrevne PDF med GET /cases/{id}/documents/{documentId}/file og signaturbeviset med GET /cases/{id}/certificate.pdf.

Forbind en AI-assistent (MCP)

Forsegl har en MCP-server (Model Context Protocol), så AI-assistenter kan arbejde direkte i Forsegl: oprette sager, tilføje dokumenter og underskrivere, sende, minde om, følge status og hente underskrevne dokumenter. Assistenten bruger jeres API-nøgle og kan det samme som API'et.

Claude Code

claude mcp add --transport http forsegl https://app.forsegl.dk/mcp \
  --header "Authorization: Bearer fsg_…"

Claude Desktop

Åbn Indstillinger → Udvikler → Rediger konfiguration, tilføj følgende, og genstart Claude. Kræver Node.js.

{
  "mcpServers": {
    "forsegl": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.forsegl.dk/mcp",
               "--header", "Authorization: Bearer fsg_…"]
    }
  }
}

Cursor, VS Code, Windsurf og andre

Klienter, der understøtter MCP over HTTP med egne headere:

{
  "mcpServers": {
    "forsegl": {
      "type": "http",
      "url": "https://app.forsegl.dk/mcp",
      "headers": { "Authorization": "Bearer fsg_…" }
    }
  }
}

MCP-værktøjer

Hvert værktøj svarer til et eller flere API-kald. Svarene er JSON, og PDF'er returneres som filer, assistenten kan gemme eller læse.

create_case kan gøre alt i ét trin: titel, besked, frist, dokumenter, underskrivere og eventuelt afsendelse.

Eksempler på prompts

• "Send vedhæftede lejekontrakt til underskrift hos Anna Holm (anna@example.com) med frist på fredag."
• "Hvilke sager venter stadig på underskrift, og hvem mangler?"
• "Send en påmindelse til alle, der ikke har underskrevet aftalerne i mappen Ansættelser."
• "Hent de underskrevne dokumenter og signaturbeviset for SG-00042."
• "Lav et nyt brand til datterselskabet med vores grønne farve, og brug det på mappen Nordic."

Konventioner

• Alle forespørgsler og svar er JSON (Content-Type: application/json), undtagen fil-downloads.
• Datoer er ISO 8601 i UTC, f.eks. 2026-12-01T22:59:00.000Z.
• Id'er er UUID'er. Sagsnummeret (reference, f.eks. SG-00042) er til mennesker og kan bruges i søgning.
• Ændringer returnerer den opdaterede sag, så I sjældent behøver at hente den igen.
• En sag er en kladde (draft), indtil den sendes. Dokumenter, underskrivere og de fleste felter kan kun ændres i en kladde.

Sagens status

Sager

Dokumenter

Dokumenter kan sendes som JSON med base64 eller en offentlig https-adresse, som Forsegl henter, eller som multipart/form-data i feltet files:

{
  "documents": [
    { "name": "Kontrakt.pdf", "contentBase64": "JVBERi0xLjcK…" },
    { "name": "Bilag 1.pdf",  "url": "https://example.com/bilag-1.pdf" }
  ]
}

Svaret indeholder sagen samt added (nye dokument-id'er) og rejected (navne på filer, der ikke var gyldige PDF'er eller ikke kunne hentes).

Underskrivere

{
  "signers": [
    { "name": "Anna Holm", "email": "anna@example.com", "title": "Direktør", "authMethod": "mitid" },
    { "name": "Erik Berg", "email": "erik@example.se", "language": "en", "authMethod": "bankid_se" },
    { "name": "Revisor", "email": "revisor@example.com", "role": "copy" }
  ]
}

Med "sequential": true på sagen underskriver de i listens rækkefølge, og den næste får først mail, når den forrige har underskrevet.

Mapper og brands

Konto

Fejl og grænser

Fejl returnerer en HTTP-statuskode og en maskinlæsbar kode:

{ "error": "not_draft" }

Grænser: 600 API-kald og 300 MCP-kald i minuttet pr. nøgle. 25 MB pr. PDF, 20 dokumenter pr. kald og 50 underskrivere pr. sag.

Webhooks

Tilføj en https-adresse under API og MCP i appen eller via API'et, så sender Forsegl en POST med JSON, når der sker noget i en sag.

Svar med en 2xx-status inden for 10 sekunder. Fejler leveringen, prøver Forsegl igen efter 30 sekunder, 5 minutter og 30 minutter. Den samme hændelse kan i sjældne tilfælde komme mere end én gang, så brug id til at se bort fra dubletter.

Hændelser

{
  "id": "evt_3b0d6f8e-…",
  "type": "case.completed",
  "createdAt": "2026-11-05T09:41:12.004Z",
  "data": {
    "case": { "id": "6f1c…", "reference": "SG-00042", "title": "Lejekontrakt, Vesterbrogade 14",
              "status": "completed", "completedAt": "2026-11-05T09:41:11.870Z" },
    "signer": null
  }
}

Verificér signaturen

Hver levering har headeren Forsegl-Signature: t=<unix-tid>,v1=<hex>. v1 er HMAC-SHA256 af "{t}.{rå body}" med webhookens hemmelighed (whsec_…). Afvis forespørgsler, hvor signaturen ikke passer, eller hvor t er mere end 5 minutter gammel.

import crypto from 'node:crypto';

export function verifyForsegl(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

import hmac, hashlib, time

def verify_forsegl(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Sikkerhed

• Al trafik går over HTTPS. Data og dokumenter opbevares hos Akamai (Linode) i Frankfurt, Tyskland.
• API-nøgler gemmes kun som hash. Mister I en nøgle, så tilbagekald den og opret en ny.
• Dokument-adresser og webhook-adresser skal være offentlige https-adresser. Interne netværk afvises.
• Personlige underskriftslinks i API-svar giver adgang til at underskrive. Behandl dem som fortrolige.
• Alt, der sker i en sag, også via API og MCP, logges i sagens hændelseslog og signaturbeviset.

Spørgsmål til integrationen? Skriv til info@wecode.dk.