Skip to main content
Use this walkthrough to connect DocuSign. Send envelopes for signature, check the status of a signing flow, download signed documents, and look up recipients. DocuSign is a great fit for Foundry because most teams need a handful of very specific things from it (send this template, check if this envelope is signed) that don’t justify a full custom integration project.
New here? Start with the OAuth setup overview for the shape and prerequisites that apply to every provider.

​
Before you begin

You’ll need:
  • Organization admin access in Ravenna.
  • A DocuSign account with permission to create apps in Settings → Apps and Keys (you’ll need to be an admin of the DocuSign account).
  • An idea of which scopes your function needs. The most common starting points:
    • signature to send and manage envelopes, the most common scope.
    • impersonation, only needed for system-to-system flows (not used in this walkthrough).
    • extended to keep tokens fresh with refresh tokens.
You’ll also need to decide whether you’re connecting to DocuSign’s demo environment (for testing) or production. The URLs are different. This walkthrough shows the production values with a note on demo.

​
1. Create the OAuth app in DocuSign

1

Open Apps and Keys

Sign in to DocuSign, click your profile in the top right, and go to Settings → Apps and Keys (under Integrations).
2

Add a new app

Click Add App and Integration Key. Give it a name like “Ravenna Foundry” and save. DocuSign generates an Integration Key. This is your client ID.
3

Add a secret key

On the app page, under Authentication, choose Authorization Code Grant and click Add Secret Key. Copy the secret immediately, since DocuSign only shows it once.
4

Add the redirect URI

Under Additional settings → Redirect URIs, add Ravenna’s callback URL:
https://app.ravenna.ai/api/integrations/foundry-oauth/callback
Replace app.ravenna.ai with your custom domain if you use one. Save.
Unlike most providers, DocuSign doesn’t let you preselect scopes when creating the app. Scopes are requested at sign-in time, and you’ll configure them in Ravenna in the next section.

​
2. Register the provider in Ravenna

1

Open Settings → OAuth Providers

In Ravenna, go to Settings → OAuth Providers and click Add Provider.
2

General tab

Fill in:
  • Name. For example, “DocuSign.”
  • Slug. docusign.
  • Description and Logo. Optional but helpful.
  • Base URL. https://www.docusign.net/restapi. (See the note below.)
  • Docs URL. https://developers.docusign.com/docs/esign-rest-api/reference/.
3

OAuth tab

Fill in the details from DocuSign:
  • Authorization URL. https://account.docusign.com/oauth/auth
  • Token URL. https://account.docusign.com/oauth/token
  • Scopes. signature extended for typical send-and-check flows. Add more if your function needs them (e.g. cors for browser-side flows).
  • Client ID. Paste the Integration Key from DocuSign.
  • Client secret. Paste the secret key you saved.
4

Research and save

Foundry researches the docs URL. Once it finishes, the provider is enabled and shows up in Settings → Integrations under the Custom category.
Demo environment instead of production? Use these URLs:
  • Authorization URL: https://account-d.docusign.com/oauth/auth
  • Token URL: https://account-d.docusign.com/oauth/token
  • Base URL: https://demo.docusign.net/restapi
Customers usually set up two providers (one demo, one production) so they can build and test against demo before pointing real users at production.
Why www.docusign.net/restapi? DocuSign routes calls through a per-account base URL. After sign-in, your function calls /oauth/userinfo to discover the user’s account ID and base URI for the account, then uses that for all subsequent calls. Foundry’s generated code can handle this. Ask in chat: “look up the user’s base URI from /oauth/userinfo and use it for envelope calls”.

​
3. Connect an account

Each user who runs a function connects their own DocuSign account once:
  1. Go to Settings → Integrations, find DocuSign in the Custom category, and click Connect.
  2. DocuSign shows the consent screen listing the scopes. Approve.
  3. You’re back in Ravenna with a connected account. The extended scope means refresh tokens are issued automatically.

​
4. Build a function on top

Open Foundry, click New Function, and connect the DocuSign provider in the function’s Integrations tab. Pick which connected DocuSign account the function should run as. Then describe what you want it to do:
  • “Send an envelope from a template by ID to a recipient with the given email and name. Return the envelope ID and status.”
  • “Look up the status of an envelope by ID. Return the overall status, plus each recipient’s status and signed-at timestamp.”
  • “Download the combined signed PDF for an envelope by ID and return it as a base64 string.”
  • “List all envelopes I’ve sent in the last 7 days that are still waiting on a signature. Return the subject, recipient email, and sent date for each.”
Full build → test → refine → publish loop: Building functions.

​
DocuSign-specific gotchas

The OAuth flow finishes but the function returns “INVALID_ACCOUNT_ID.” Your function is calling the API with the wrong account ID. After sign-in, call https://account.docusign.com/oauth/userinfo. It returns an accounts array with each account’s account_id and base_uri. Use those values for envelope calls. Ask Foundry in chat to “fetch userinfo first and use the default account’s base_uri”, and it’ll add the lookup. Tokens stop working after 8 hours. You didn’t include the extended scope, so DocuSign isn’t issuing refresh tokens. Add it to the Scopes field in Settings → OAuth Providers and have users reconnect. You’re testing against demo but envelopes never appear. The connected user signed in to the production environment. Demo and production are completely separate, with different accounts and different URLs. Register a second provider that points at the demo URLs (see the demo note above) and have testers connect that one. A user can connect but only sees one account they don’t want. DocuSign returns every account the user belongs to in userinfo. If they have multiple, the function needs to pick by account_id. Add that as an input on the function so callers can specify which account to act against.
Last modified on June 4, 2026