Skip to main content

DocuSign

Connecting DocuSign lets Loyva mirror your DocuSign envelopes into the Documents page, link signers to customers, and vault completed agreements into your UCC §9-105 e-vault.

Connect from Settings → Integrations → DocuSign. There are two ways to connect — pick one at the top of the panel:

MethodBest forWhat you provide
OAuth sign-in (recommended)Most accountsA one-click sign-in — nothing to paste
API keys (JWT Grant)Headless / unattended setups, or admins who don't want a browser sign-in per connectionYour own Integration Key, an RSA key pair, and the API user to act as

Both methods produce the same result: Loyva reads your account's envelopes and downloads completed PDFs. They differ only in how the account is authorized.

Method 1 — OAuth sign-in (recommended)​

  1. Open Settings → Integrations → DocuSign.
  2. Choose OAuth sign-in and click Connect DocuSign.
  3. Sign in to DocuSign and approve access.
  4. You're returned to Loyva with the account linked.

DocuSign itself recommends this flow whenever a person is present to sign in. Loyva stores a refresh token and keeps the connection alive automatically — there's nothing to rotate.

Method 2 — API keys (JWT Grant)​

JWT Grant is DocuSign's service-integration flow. After a one-time consent, Loyva mints short-lived access tokens by signing a JWT with your RSA key — no browser sign-in per token.

note

DocuSign has no Stripe-style static API key. JWT Grant is the closest no-redirect option. It requires admin access to your DocuSign account and is more setup than OAuth, so use it only when you specifically need an unattended connection.

Prerequisites (in your DocuSign admin)​

  1. Create an Integration Key (Client ID) under Settings → Apps and Keys.
  2. Generate an RSA key pair on that Integration Key. Save the private key — DocuSign only shows it once. Loyva needs the private key; DocuSign keeps the public key.
  3. Add a redirect URI on the Integration Key so consent can complete. Use: 
    https://<your-loyva-app-domain>/oauth/docusign/callback
  4. Find the API user's ID — the API Username (a GUID) of the user Loyva should act as, under Settings → Users.

Connect in Loyva​

  1. Open Settings → Integrations → DocuSign and choose API keys (JWT Grant).
  2. Enter:
    • Integration Key (Client ID) — from step 1 above
    • API User ID — the API Username GUID from step 4
    • RSA Private Key — paste the PEM private key from step 2 (-----BEGIN RSA PRIVATE KEY----- … or -----BEGIN PRIVATE KEY-----)
  3. Click Connect with API keys.

The first connection attempt usually returns a prompt that consent is required. This is a one-time DocuSign approval:

  1. Click Grant consent in DocuSign in the panel.
  2. Sign in as a DocuSign admin and approve.
  3. Return to Loyva and click Connect with API keys again — it now succeeds.

If your admin grants consent organization-wide, no individual user sees this prompt again.

How tokens work​

JWT access tokens last one hour and carry no refresh token. Loyva re-mints a fresh token on demand from your stored credentials, so the connection stays live without any rotation on your side.

Security

The RSA private key is a long-lived signing secret. Treat it like a password — anyone holding it can act as the API user. Loyva stores it to re-mint tokens; revoke it in DocuSign (or Disconnect in Loyva) if it's ever exposed.

What gets synced​

Once connected, Loyva periodically:

  • Mirrors your envelopes into the Documents page (read-only — the authoritative copy stays in DocuSign until you vault it).
  • Optionally queues unrecognized signers for review so you can link them to customers.
  • Lets you vault a completed agreement, which downloads the signed PDF and runs the UCC §9-105 compliance pipeline.

Use the Sync documents toggle on the connection card to turn the Documents mirror on or off.

Disconnecting​

Click Disconnect on the connection card. This deactivates the connection and stops syncing. Re-connecting (by either method) reactivates it.

Troubleshooting​

SymptomCauseFix
"Consent required" on JWT connectThe API user hasn't granted consent yetClick Grant consent in DocuSign, approve as an admin, then connect again
"Failed to authenticate … JWT credentials"Wrong Integration Key, API User ID, or private key — or the public key isn't registered on the Integration KeyRe-check all three values; confirm the RSA key pair is the one on this Integration Key
Consent redirect shows an errorThe redirect URI isn't registered on your Integration KeyAdd https://<your-loyva-app-domain>/oauth/docusign/callback to the Integration Key's redirect URIs
"DocuSign is not configured on this environment" (OAuth only)The environment is missing Loyva's platform DocuSign credentialsUse API keys (JWT Grant) instead, or contact Loyva