> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth setup for DocuSign

> Create a DocuSign OAuth app, register it as a Foundry OAuth provider in Ravenna, and use it to send envelopes, check signing status, and fetch signed documents.

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.

<Callout icon="link" color="#6B7280">
  New here? Start with the [OAuth setup overview](/guides/how-to/foundry/setup-oauth/overview) for the shape and prerequisites that apply to every provider.
</Callout>

***

## 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

<Steps>
  <Step title="Open Apps and Keys">
    Sign in to DocuSign, click your profile in the top right, and go to **Settings → Apps and Keys** (under Integrations).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  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.
</Info>

***

## 2. Register the provider in Ravenna

<Steps>
  <Step title="Open Settings → OAuth Providers">
    In Ravenna, go to **Settings → OAuth Providers** and click **Add Provider**.
  </Step>

  <Step title="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/`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  **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.
</Info>

<Info>
  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".
</Info>

***

## 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."

<Callout icon="link" color="#6B7280">
  Full build → test → refine → publish loop: [Building functions](/documentation/automate/foundry/actions).
</Callout>

***

## 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.