Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firma.dev/llms.txt

Use this file to discover all available pages before exploring further.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha’s AI to call the API from your backend, and your users can send signing requests directly from your app. This guide covers how to integrate Firma using Mocha’s built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

​
Prerequisites

  • A Firma account with an API key
  • A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
  • At least one Firma template with signing fields configured
Firma uses the raw API key as the Authorization header value — do not prefix it with Bearer. This differs from many other APIs.

​
Step 1: Store your Firma API key as a secret

  1. Open your project in Mocha
  2. Go to Settings → Secrets
  3. Add a new secret with the name FIRMA_API_KEY and paste your Firma API key as the value
Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code. To get your API key, log in to the Firma dashboard, go to Settings → API Keys, and copy your key.

​
Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don’t need to write code yourself. Instead, paste the following prompt into the Mocha chat: 
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
Replace YOUR_TEMPLATE_ID with the ID of a template from your Firma dashboard. You can find it under Templates by clicking on a template and copying the ID from the URL. Mocha’s AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.
The create-and-send endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use POST /signing-requests to create a draft first, then POST /signing-requests/{id}/send separately.

​
Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:
  1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
  1. After publishing your app, copy the webhook URL: https://your-app.mocha.app/api/webhook/firma
  2. In the Firma dashboard, go to Settings → Webhooks and register this URL
For production use, always verify the webhook signature using your Firma webhook signing secret. See the webhooks guide for implementation details.
See the webhooks guide for all event types and payload details.

​
Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The create-and-send response includes a first_signer.id (the signing_request_user_id) and a ready-made first_signer.signing_link. Ask Mocha to add an iframe that loads the signing URL: 
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
See the embedded signing guide for full setup instructions and security best practices.

​
Bonus: Use Custom Knowledge for better AI results

Mocha’s Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.
  1. Open your project and go to the Custom Knowledge tab
  2. Add the following:
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

​
Next steps