> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Use a manifest file to register an extension app

> This guide describes the steps for registering an extension app by building a JSON app manifest file.

This guide describes the steps for registering an extension app by building a JSON app manifest file. You also have the option of registering an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). See [Form-based and app manifest method comparison](/extension-apps/build-an-extension-app/register#form-based-and-app-manifest-method-comparison) for guidance about which method might be more useful.

The example code in this procedure implements a file output to cloud storage [use case](/extension-apps/build-an-extension-app/example-use-case).

> **Note**
>
> Before starting this procedure, make sure that you have completed or obtained the items listed in [Prerequisites for registering an extension app](/extension-apps/build-an-extension-app/register#prerequisites-for-registering-an-extension-app).

## Step 1. Register a new app in the Developer Console

Open the [Developer Console](https://devconsole.docusign.com) and select **Create App**, and then **By editing the manifest** in the upper right corner of the screen.

## Step 2. Create an extension app manifest

The app manifest editor opens, containing an extension app manifest template. This is where you will create or upload the [extension app manifest](/extension-apps/extension-apps-101/concepts/extension-app-manifest). The app manifest is a JSON file that defines these parameters for an extension app:

* [Connection](/extension-apps/extension-apps-101/concepts/connections)
* [Extensions](/extension-apps/extension-apps-101/concepts/extensions-and-extension-points)
* [Actions](/extension-apps/extension-apps-101/concepts/actions)

  See [What's inside an extension app](/extension-apps/extension-apps-101/inside-an-extension-app) for details about how these components function.

![A screenshot of the JSON editor in the Developer Console](/_fern-files/_img/7b70fd219fdd29c2c5f2d9889d8d3f3396c2b0d09b2797dd847c731a22bc817a.webp)

You can create and edit your manifest directly in the manifest editor, or you can use the buttons in the top right corner of the manifest editor to download or copy the manifest template to edit it in the IDE of your choice. You can also download the manifest template by choosing **Download** under **Download a template** in the left column on the screen shown above. If you edited your manifest in your IDE, save it as a JSON file and upload it, either by dragging and dropping the file in the box on the left of the screen shown above, or by choosing **Select File**. After your manifest has been uploaded, it will replace the manifest template in the app manifest editor. You can continue to make any necessary edits in the manifest editor.

### Extension app information

The properties defined at the beginning of the extension app manifest—the name, short and long descriptions, images, publisher details, and relevant URLs—will appear in the [Docusign App Center](/extension-apps/extension-apps-101/app-center) when the extension app is published. Each extension app that you create needs to have a unique name. The `distribution` property determines whether your app will be [public or private](/extension-apps/extension-apps-101/choosing-private-distribution). The value of `distribution` cannot be changed once the app is live. You can change the `distribution` value when the app is in **Draft**, **Approved**, or **Rejected** status.

The `publicationRegions` property determines the regions in which the app will be available for production use. Once an app is live, you can add regions, but you cannot remove them. See [Globalization](/extension-apps/extension-apps-101/globalization) for more information.

To add an icon to your extension app, set the value of `icon.data` to the Base64 representation of your image. Set the value of `icon.mediaType` to the [media type](/extension-apps/extension-app-reference/app-manifest-reference) of the icon.

To convert an image file to Base64, you can use commands like these:

* Windows (PowerShell): `[Convert]::ToBase64String((Get-Content TestImage.png -Encoding Byte)) >> output.txt`
* UNIX/Linux: `cat TestImage.png | base64 | pbcopy`

A number of Base64 image converter utilities are also available on the internet. Guidelines for icons and screenshots appear in [Extension app best practices](/extension-apps/best-practices).

**`JSON`**

```json title="JSON"
{
"name": "File Output Cloud Storage",
"description": {
"short": "This is a sample short description",
      "long": "This is a sample long description"
},
"publisher": {
"name": "Fontara",
      "email": "sampleemail@fontara.com"
},
"termsOfServiceUrl": "https://www.fontara.com/tos",
"privacyUrl": "https://www.fontara.com/privacy-security",
"supportUrl": "https://www.fontara.com/support",
"icon": {
"data": "54ba2e...097bf1=",
"mediaType": "image/png"
},
"signupUrl": "https://www.fontara.com/signup",
"changelog": "",
"publicationRegions": [
"US"
],
"distribution": "PUBLIC"
}
```

### Connections

The next section of the extension app manifest defines the extension app’s connections. The  [connection object](/extension-apps/extension-app-reference/app-manifest-reference/connection) contains all of the data needed to connect with an external API, API proxy, or identity provider. The connection name must be a unique value that will be used again later when defining the extension app’s actions. Within the `connections` object, set these values within the `params` property:

* `clientId` and `clientSecret`: These values should come from the external platform or identity provider.
* `provider`: This value should be set to `CUSTOM`.
* `scopes`: List any scopes that need to be requested during authorization.
* `grantType`: Indicates whether the extension app uses [Authorization Code Grant](/extension-apps/build-an-extension-app/it-infrastructure/authorization#authorization-code-grant) (`authorization_code`) or [Client Credentials Grant](/extension-apps/build-an-extension-app/it-infrastructure/authorization#client-credentials-grant) (`client_credentials`).
* `customConfig`: The `customConfig` object that will store the following properties related to your extension app’s custom configuration:

  * `tokenUrl` and `authorizationUrl`: Set these values to the endpoints for getting the token and authorization.
  * `authorizationParams`: Use this property to store any query parameters needed for the authorization endpoint.
  * `authorizationMethod`: Set this value to either `header` or `body`.
  * `scopeSeparator`: Set this value to the delimiter that will be used to separate your needed scopes.

**Note**: Docusign automatically generates a `redirect_uri` value based on your provided `authorizationUrl` and passes this value back to you as a query parameter. Do not hard-code the `redirect_uri`. It may contain one of several values, depending on your region and environment. See [Authorization](/extension-apps/build-an-extension-app/it-infrastructure/authorization) for details.

**`JSON`**

```json title="JSON"
"connections": [
       {
           "name": "authentication",
           "description": "Secure connection to sample extension app",
           "type": "oauth2",
           "params": {
               "provider": "CUSTOM",
               "clientId": "[omitted]",
               "clientSecret": "[omitted]",
               "scopes": [],
               "grantType": "authorization_code",
               "customConfig": {
                   "authorizationMethod": "header",
                   "authorizationParams": {
                       "prompt": "consent",
                       "access_type": "offline"
                   },
                   "authorizationUrl": "https://www.fontara.com/api/oauth/authorize",
                   "requiredScopes": [],
                   "scopeSeparator": " ",
                   "tokenUrl": "https://www.fontara.com/api/oauth/token",
                   "refreshScopes": []
               }
           }
       }
   ],
```

### Extensions

After defining your extension app’s connections, you can create an `extensions` object to define the group of tasks that your extension app executes and an `actions` object to define each one of those tasks. In the `extensions` object, define the following properties:

* `template`: This value should be set to the unique string identifier that references the predefined [extension contract](/extension-apps/extension-app-reference/extension-contracts) for your extension provided by Docusign.
* `actionReferences`: List the actions that make up your extension.

  > **Note**
  >
  > The names in the `actionReferences` object must match the names of actions defined in the `actions` object of your extension app manifest.
* `capabilities`: List the optional capabilities that make up your extension. The names listed here should match the names of actions defined in the actions object of your extension app manifest. Not all extension types currently support capabilities.

**`JSON`**

```json title="JSON"
"extensions": [
       {
           "name": "File Output Cloud Storage",
           "description": "Used to store files to cloud storage",
           "template": "FileIO.Version1.FileOutputCloudStorage",
           "actionReferences": [
               "write-file",
               "list-directory-contents",
               "list-drives"
           ],
           "capabilities": [
               "FileIO.Version1.ListDirectoryContents",
               "FileIO.Version1.ListDrives"
           ]
       }
 ],
```

### Actions

To define the extension's [actions](/extension-apps/extension-apps-101/concepts/actions), add them to your extension app manifest in the list of actions. Optional [capabilities](/extension-apps/extension-apps-101/concepts/capabilities) can also be added to this list for extensions where capabilities are supported.

* `name` and `description`: These values describe your action and give it a name. The value of `name` will be referenced in the `actionReferences` field in the `extensions` object. For file IO extensions, Docusign predefines the name values. See the [extension contract](/extension-apps/extension-app-reference/extension-contracts) reference for details. For other extensions, any value can be used.
* `template`: This value defines the contract of the action and should be set to the unique string identifier of the template for the contract. You can access the action contracts for each extension from the [Extension contracts](/extension-apps/extension-app-reference/extension-contracts) page.
* `connectionsReference`: This value should match the value of the `name` parameter in the `connections` object in your extension app manifest.
* `params`: Use this parameter to specify the external API endpoint or API proxy endpoint that will be called by the action.

**`JSON`**

```json title="JSON"
"actions": [
       {
           "name": "write-file",
           "description": "This is a description of my write file action",
           "template": "FileIO.Version1.WriteFile",
           "connectionsReference": "authentication",
           "params": {
               "uri": "https://www.fontara.com/api/writefile"
           }
       },
       {
           "name": "list-drives",
           "description": "This is a description of my list drives action",
           "template": "FileIO.Version1.ListDrives",
           "connectionsReference": "authentication",
           "params": {
               "uri": "https://www.fontara.com/api/listdrives"
           }
       },
       {
           "name": "list-directory-contents",
           "description": "This is a description of my list directory contents action",
           "template": "FileIO.Version1.ListDirectoryContents",
           "connectionsReference": "authentication",
           "params": {
               "uri": "https://www.fontara.com/api/listdirectorycontents"
           }
       }
 ],
```

### Screenshots

Finally, to add screenshots to your extension app, set the value of `screenshots[].data` to the Base64 representation of your images. Set the value of `screenshots[].mediaType` to the media type of the screenshot. You can add up to four screenshots.

This JSON snippet shows how the parameters appear in the extension app manifest.

Once you have set all of those values, your extension app manifest is ready to be uploaded and validated. See the [App manifest reference](/extension-apps/extension-app-reference/app-manifest-reference) for a full list of supported elements.

**`JSON`**

```json title="JSON"
"screenshots": [
    {
      "data": "VBERi0...VPRgo=",
      "mediaType": "image/png"
    }
]
```

## Step 3. Validate your app manifest

When your app manifest is ready, select **Validate** to determine if your manifest has any errors. See [Troubleshooting manifest errors](/extension-apps/extension-app-reference/app-manifest-reference/troubleshooting-manifest-errors) for a list of possible errors with details on how to troubleshoot them. Once your manifest has passed all validation checks, you can choose **Create App** to finish registering your application.

## Next steps

* Learn how to [Test an extension app](/extension-apps/build-an-extension-app/test).
* Review [Example extension app use cases](/extension-apps/build-an-extension-app/example-use-case).
* [Publish an extension app](/extension-apps/build-an-extension-app/publish) on the Docusign App Center.