How FranConnect authenticates to and interacts with your DocuSign account
Overview
FranConnect can send documents for electronic signature through your own DocuSign account. This article explains exactly how that connection is established, what FranConnect stores, what it can and cannot do inside your DocuSign account, and how you can restrict or revoke access at any time.
It is written for administrators, IT teams, and security reviewers who need a precise answer to the question: “What can FranConnect access in our DocuSign account?”
1. Summary at a Glance
| Question | Answer |
| Authentication model | DocuSign OAuth 2.0 Authorization Code Grant, consented interactively by your own DocuSign user. No JWT, no impersonation, no stored DocuSign passwords. |
| Credentials stored | Per-user DocuSign access and refresh token, account ID, and DocuSign login email, held in your tenant’s own database. FranConnect’s integration key and secret are platform-level, not customer data. |
| Scopes granted | signature — that is the complete list. One scope. |
| Operations available | Read templates and field definitions; create and send envelopes; set recipient field values; read envelope and recipient status; download completed documents. |
| Boundaries | No user or account administration, no account settings, no voiding/deleting/purging of envelopes, no signing on a recipient’s behalf, no cross-account or organization access. |
| Email access | None. No mail client of any kind exists in the service. The stored email address is an identifier returned by DocuSign. |
| Tenant isolation | Confirmed. Tokens are held in a per-tenant database and keyed per user; nothing is shared between customers. |
| Customer control | You can revoke access unilaterally in DocuSign at any time; access is also removable per module inside FranConnect. |
2. Authentication Model
FranConnect uses the DocuSign OAuth 2.0 Authorization Code Grant (three-legged, user-consented). It does not use JWT Grant, DocuSign Impersonation, stored DocuSign account credentials, or any legacy password-based authentication header.
How the connection is established
- Open the configuration screen. A FranConnect user opens the DocuSign configuration screen for a module. FranConnect redirects them to DocuSign’s own authorization endpoint, requesting response_type=code and scope=signature.
- Authenticate and consent at DocuSign. The user signs in to DocuSign and grants consent there. FranConnect never sees their DocuSign password.
- Exchange the authorization code. DocuSign returns an authorization code. FranConnect exchanges it server-to-server for an access token and a refresh token, authenticating as its registered application with grant_type=authorization_code.
- Call the API with the token. All subsequent DocuSign API calls carry the OAuth access token as a bearer token.
- Refresh before expiry. Access tokens last 8 hours. FranConnect treats a token as stale at roughly 7 hours and refreshes it using the refresh token.
Note: Consent is granted per FranConnect user, per module — not as a single account-wide service credential. Each user who wants to send envelopes authorizes their own DocuSign identity.
3. Credentials and Identifiers Stored
3.1 Tenant-specific (your data)
The following is held inside your own FranConnect database:
| Field | Purpose |
| FranConnect user + module | Identifies which user and module the authorization belongs to |
| Access token | Bearer token for DocuSign API calls (8-hour lifetime) |
| Refresh token | Used to obtain a new access token without re-prompting the user |
| Token timestamps | Freshness tracking |
| Account ID | The DocuSign account the user authorized |
| Login email | The DocuSign login email as returned by DocuSign, shown in the FranConnect UI as “logged-in email.” Identifier only — see Section 7. |
Also held per tenant: raw DocuSign status callbacks and field-mapping configuration. A customer who supplies their own DocuSign integration key instead of using FranConnect’s may also have that key stored for their tenant.
3.2 Platform-level (FranConnect’s own, not customer credentials)
FranConnect’s own DocuSign application Integration Key and secret represent the identity of the FranConnect application itself — equivalent to any ISV’s client credentials. Also platform-level: the DocuSign endpoint URLs, and an envelope-ID-to-tenant lookup used to route inbound status callbacks to the correct tenant.
3.3 Explicitly not stored
- DocuSign usernames or passwords
- Email account credentials of any kind — no mailbox password, OAuth token, app password, or API key for any mail provider
- Any customer-supplied secret beyond the optional bring-your-own DocuSign integration key
4. DocuSign Permissions and OAuth Scopes
The complete scope list requested is: signature. One scope.
Not requested, and therefore not granted: extended, impersonation, user_read, user_write, account_read, organization_read, group_read, permission_read, and any dtr.*, click.*, or Rooms scopes.
Two consequences are worth stating explicitly:
- signature grants access to the eSignature REST API acting as the single user who consented — it confers no administrative rights.
- Access is additionally capped by that user’s own DocuSign permission profile. If you authorize a restricted DocuSign user, FranConnect inherits exactly those restrictions. This is your primary lever for limiting access.
5. Operations FranConnect Can Perform
After authentication, FranConnect performs only the following read and write operations:
| Operation | DocuSign eSignature API |
| Identify the authorized account | Login/account information |
| List templates | Read templates |
| Read template recipients and tabs | Read template recipients/tabs |
| Preview a template document | Read template document |
| Read field/tab definitions for mapping | Read tab and custom-field definitions |
| Create and send an envelope | Create envelope |
| Set recipient field (tab) values on an envelope | Update recipient tabs |
| Generate a sender view URL | Create sender view |
| List envelope status changes | Read envelope status |
| Download completed documents | Read envelope documents |
| Read signed field values | Read recipient/document tabs |
Writes are limited to creating envelopes and setting recipient field values. There is no ability to administer the account or to void, delete, or purge envelopes.
5.1 Status callbacks (DocuSign Connect)
Each envelope FranConnect creates carries its own event-notification block in the create-envelope request, pointing at a FranConnect endpoint. Subscribed events are: sent, delivered, completed, declined, and voided, plus the equivalent recipient events.
Important: This is configured per envelope. FranConnect never modifies your account-level DocuSign Connect configuration.
6. Access Boundaries — What FranConnect Cannot Do
| FranConnect cannot… | Basis |
| Administer users, groups, or permission profiles | No such API calls are made |
| Read or change account settings, billing, or branding | No such API calls are made |
| Change the account’s Connect / webhook configuration | Event notifications are set per envelope only |
| Void, delete, purge, or correct envelopes | No void/delete/correct calls are made; writes are limited to creating envelopes and setting recipient field values |
| Sign on a recipient’s behalf | No embedded-signing or recipient-view calls; sender view only |
| Impersonate other DocuSign users | No JWT Grant, no impersonation scope |
| Reach organization-wide data | No organization API calls, no organization_read scope |
| Use any account other than the authorized one | Bound to the authorizing user’s default login account |
| Exceed the authorizing user’s own rights | The signature scope operates strictly in that user’s context and permission profile |
7. Email Access
FranConnect has no access to any customer email account or mailbox. The DocuSign integration contains no mail client of any kind — no IMAP, SMTP, POP, Microsoft Graph, or Gmail capability exists in the service, so it could not connect to a mailbox even if credentials were supplied.
The configured email address is purely an identifier:
- It is not entered by you as a credential. It is returned by DocuSign after the user consents.
- It is stored and displayed in the configuration screen so an administrator can see which DocuSign identity a module is connected as.
- It is never used to authenticate to, read from, or send from any mail system.
Signer email addresses come from your own FranConnect records and are passed to DocuSign as envelope recipients. DocuSign — not FranConnect — sends the signature-request emails.
8. Tenant Isolation
Credentials, configuration, and resulting access are tenant-specific, and additionally scoped per user. Nothing is shared between customers.
- Data separation. DocuSign tokens live in each tenant’s own database, selected from the request’s tenant context on every connection. A query issued in one tenant’s context cannot address another tenant’s data.
- Per-user granularity. Access is keyed to the individual user and module. A user’s DocuSign access is bounded by their own consent and by the modules enabled for them.
- Blast radius. Because each token is bound at DocuSign to the account and user that consented, a token could not grant access to a different customer’s DocuSign account.
Shared across tenants by design — these are FranConnect’s own assets and contain no customer credentials: the FranConnect application’s integration key and secret, the DocuSign endpoint URLs, and the envelope-ID-to-tenant routing lookup for inbound status callbacks.
9. Security Controls and Customer Control
| Control | Implementation |
| Revoke unilaterally | Remove the FranConnect application under DocuSign Settings → Apps and Keys / Connected Apps. The next token refresh fails and the integration stops — no action required by FranConnect. |
| Disable inside FranConnect | Removing the module account deletes the stored token outright. DocuSign can also be enabled or disabled per module. |
| Scope limitation | A single signature scope, further limitable by authorizing a DocuSign user with a restricted permission profile. |
| Token rotation | Tokens are short-lived (8 hours) and refreshed roughly every 7 hours; each refresh persists the newly issued tokens. |
| Consent model | Per user, per module. No shared service account, no account-wide grant. |
| API authentication | The service is an OAuth 2.0 resource server; its functional endpoints require a valid access token. |
| Transport | Outbound DocuSign traffic uses HTTPS (TLS 1.2). |
10. How to Revoke FranConnect’s Access
You can disconnect the integration at any time, from either side.
From DocuSign (revokes at the source)
- Sign in to DocuSign.
- Go to Settings → Apps and Keys (or Connected Apps).
- Locate the FranConnect application and remove it.
The next token refresh will fail and the integration stops working. No action is required by FranConnect.
From FranConnect
- Open the DocuSign configuration screen for the module.
- Remove the connected module account. This deletes the stored token outright.
DocuSign can also be enabled or disabled per module.