Skip to main content

Reuse the signer or create one per request: mapping your users to IgniSign signers

· 4 min read
Julien Jenoudet
Julien Jenoudet
CEO of IgniSign

Your product already has users. The first time one of them signs inside your app, IgniSign needs a signer: a record with a name, an email and whatever else the signer profile asks for. The second time the same user signs, you face a small decision that shapes your integration: do you point the new signature request at the signer you already have, or describe the person again on the new request?

What a signer is in IgniSign​

A signer belongs to one application and one environment. The same person in two of your applications is two signers, and the signer you created in development is not the one you will use in production.

The signer profile decides what a signer needs. A simple signature can start from an email. An advanced one adds a second factor (an SMS code, or a TOTP app or passkey that the signer registers once) and, depending on the profile, identity claims to verify. Those claims are attached to the signer.

You can create signers in two ways:

  • the create-signer call (POST /v4/applications/{appId}/envs/{appEnv}/signers) takes the signer profile, the fields that profile requires and an optional externalId. It returns a signerId, an alreadyExists flag and, for embedded flows, an authSecret;
  • the one-call signature request (POST /v4/signature-requests/one-call-sign) takes the signers inline, by email, name and signer profile, together with the documents.

Option 1: one IgniSign signer per user​

Create the signer once, when the user first reaches a flow that signs, and store the signerId next to your own user record. Put your user id in externalId, a free-form reference that IgniSign does not use internally, so anyone debugging a flow can go from one side to the other.

This fits when:

  • users come back and sign again: monthly mandates, HR documents, renewals;
  • the flow is embedded. The signer's authSecret is the first factor your app hands over when it opens the signing session, so you need a stable place to keep it. Store it server-side like any credential and give it only to the page of the user it belongs to;
  • the flow uses advanced signatures. The registered second factor and any verified claims live on that signer. A second signer record for the same person does not carry them.

Before you create, the Get Signer Creation Constraints call tells you which inputs the chosen signer profile requires, so you send those and nothing more. If a profile later needs one more input, update the existing signer rather than creating a second one.

Option 2: describe the signer on each request​

The one-call request is the shortest path from "this needs a signature" to a request that exists. You pass the title, the signature method, the signers and the documents, and your code keeps no signer state.

This fits when:

  • the signer is a one-off counterparty who will not sign in your product again;
  • the flow is BySide with simple signatures, where IgniSign invites the signer by email and nothing has to be carried between requests;
  • you are prototyping in development and want the full loop running before you design the data model.

The cost shows up later. If the same person signs every month, nothing in your database says which IgniSign signer they are, and the one-call request has no field to point at a signer you already have.

A rule that holds up​

Ask one question per flow: will this person sign in my product again, at the same level? If yes, keep one signer per user, per application and per environment, with the signerId and your externalId stored side by side. If no, describe the signer on the request and keep your schema small.

Most products end up with both. The contract a new account's admin signs at onboarding uses a persistent signer, because that admin will sign the renewal too. The one-time acceptance from an outside party goes through one-call.

The decision​

Treat the signer as part of your user model when people sign more than once, and as part of the request when they sign once. Try both patterns in your development environment first, and remember that signers there are separate from production: the code that creates signers runs again when you switch to production keys.