App Overrides

Some apps need configuration details that your end users don’t have, or shouldn’t have to enter. An app override lets workspace and project admins define those values once, so end users can connect their accounts without them.

The problem app overrides solve

Take ServiceNow. To connect a ServiceNow account, Pipedream needs:

Instance name — the host portion of the instance URL, for example dev123 in https://dev123.service-now.com
OAuth client ID
OAuth client secret

Asking your end users for this is a poor experience:

They often don’t have the information, because of permissions or lack of technical context.
They can enter it incorrectly — typos, the wrong host, missing context.
Admins can’t make sure that every user connects with the same configuration.

With an app override, an admin defines the instance name once, and optionally attaches a custom OAuth client. When an end user connects, Pipedream reads the pre-defined values from the override, asks the user only for the fields that remain, then starts the connection flow.

How overrides are scoped

Each override is owned by a workspace or a project. The owner_id field shows which:

Prefix	Owner
`o_`	Workspace
`proj_`	Project

When you list overrides for a project, the response includes the project’s own overrides and those of its parent workspace. Override names are unique per owner.

End-to-end example

This example creates a custom OAuth client for ServiceNow, pre-defines the instance name in an override, then connects an end user’s account with it.

Create a custom OAuth client

Workspaces and projects can use their own OAuth clients instead of Pipedream’s official ones. Pipedream calls these OAuth clients, and each one stores a client ID and secret, scopes, and a name and description. Read more about OAuth clients.Skip this step if the app is key-based, or if you want to keep using Pipedream’s official OAuth client. The app must also have custom OAuth clients enabled.

The clientId and clientSecret you pass here are the credentials ServiceNow issued to you. They are not your Pipedream OAuth credentials, which you pass to the client constructor.

import { PipedreamClient } from "@pipedream/sdk";

const client = new PipedreamClient({
  projectEnvironment: "development",
  projectId: "{your_pipedream_project_id}",
  clientId: "{your_pipedream_oauth_client_id}",
  clientSecret: "{your_pipedream_oauth_client_secret}"
});

const oauthApp = await client.oauthApps.create({
  app: "servicenow",
  name: "Acme ServiceNow",
  clientId: "{your_servicenow_client_id}",
  clientSecret: "{your_servicenow_client_secret}"
});

console.log(oauthApp.id); // oa_a1b2c3, use this in the next step
console.log(oauthApp.redirectUri); // Register this URI with ServiceNow

from pipedream import Pipedream

pd = Pipedream(
    project_environment="development",
    project_id="{your_pipedream_project_id}",
    client_id="{your_pipedream_oauth_client_id}",
    client_secret="{your_pipedream_oauth_client_secret}"
)

oauth_app = pd.oauth_apps.create(
    app="servicenow",
    name="Acme ServiceNow",
    client_id="{your_servicenow_client_id}",
    client_secret="{your_servicenow_client_secret}"
)

print(oauth_app.id)  # oa_a1b2c3, use this in the next step
print(oauth_app.redirect_uri)  # Register this URI with ServiceNow

curl -X POST https://api.pipedream.com/v1/connect/{project_id}/oauth_apps \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "servicenow",
    "name": "Acme ServiceNow",
    "client_id": "{your_servicenow_client_id}",
    "client_secret": "{your_servicenow_client_secret}"
  }'

Each OAuth client returns a unique redirect_uri. Register it with the third-party app so it redirects users back to Pipedream.

The client secret is write-only. Pipedream never returns it in a response. On update, a blank value keeps the existing secret.

Find the app's custom fields

An override pre-defines the custom fields that an app declares. Retrieve the app to read them from custom_fields_json, which is a JSON string you need to parse.

const { data: app } = await client.apps.retrieve("servicenow");
const customFields = JSON.parse(app.customFieldsJson ?? "[]");

console.log(customFields.map((field) => field.name)); // ["instance_name"]

import json

app = pd.apps.retrieve(app_id="servicenow").data
custom_fields = json.loads(app.custom_fields_json or "[]")

print([field["name"] for field in custom_fields])  # ["instance_name"]

curl https://api.pipedream.com/v1/connect/apps/servicenow \
  -H "Authorization: Bearer <access_token>"

For ServiceNow, the custom field is named instance_name.

Create the app override

Pass the custom field values in cfmap, keyed by the field names from the previous step. Attach the OAuth client from step 1 with oauthAppId.

const appOverride = await client.appOverrides.create({
  app: "servicenow",
  name: "Acme production instance",
  oauthAppId: oauthApp.id, // From step 1
  cfmap: {
    instance_name: "dev123"
  }
});

console.log(appOverride.id); // ao_x1y2z3, use this when connecting accounts

app_override = pd.app_overrides.create(
    app="servicenow",
    name="Acme production instance",
    oauth_app_id=oauth_app.id,  # From step 1
    cfmap={
        "instance_name": "dev123"
    }
)

print(app_override.id)  # ao_x1y2z3, use this when connecting accounts

curl -X POST https://api.pipedream.com/v1/connect/{project_id}/app_overrides \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "servicenow",
    "name": "Acme production instance",
    "oauth_app_id": "oa_a1b2c3",
    "cfmap": {
      "instance_name": "dev123"
    }
  }'

Sensitive custom fields, meaning any field of type password, can’t be pre-defined. The API rejects them in cfmap.

Connect an account

Pass the override’s ID as appOverrideId when the end user connects. Pipedream applies the pre-defined field values and the attached OAuth client, then asks the user only for the fields that remain.

client.connectAccount({
  app: "servicenow",
  appOverrideId: "ao_x1y2z3",
  onSuccess: (account) => {
    console.log(`Account successfully connected: ${account.id}`)
  },
  onError: (err) => {
    console.error(`Connection error: ${err.message}`)
  },
});

# Add appOverrideId to the query string of the Connect Link URL
https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app=servicenow&appOverrideId=ao_x1y2z3

See the Connect quickstart for the full account connection flow, and Connect Link if you don’t run JavaScript in your frontend.

Updating and removing overrides

Update an override to change its name, cfmap, or oauthAppId.
To detach a custom OAuth client and fall back to the official one, set oauthAppId to null on update.
Deleting an override does not disconnect accounts that were already connected with it.

Getting Started

Connect

Workflows

Platform

Additional Resources

The problem app overrides solve

How overrides are scoped

End-to-end example

Updating and removing overrides

API reference

App Overrides

OAuth Clients

​The problem app overrides solve

​How overrides are scoped

​End-to-end example

​Updating and removing overrides

​API reference

App Overrides

OAuth Clients

The problem app overrides solve

How overrides are scoped

End-to-end example

Updating and removing overrides

API reference