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

# App Overrides

> Pre-configure app-specific fields so your end users don't have to provide them

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.

<Steps>
  <Step title="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](/docs/connect/managed-auth/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.

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

    <CodeGroup>
      ```typescript TypeScript theme={null}
      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
      ```

      ```python Python theme={null}
      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
      ```

      ```sh cURL theme={null}
      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}"
        }'
      ```
    </CodeGroup>

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

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

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

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const { data: app } = await client.apps.retrieve("servicenow");
      const customFields = JSON.parse(app.customFieldsJson ?? "[]");

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

      ```python Python theme={null}
      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"]
      ```

      ```sh cURL theme={null}
      curl https://api.pipedream.com/v1/connect/apps/servicenow \
        -H "Authorization: Bearer <access_token>"
      ```
    </CodeGroup>

    For ServiceNow, the custom field is named `instance_name`.
  </Step>

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

    <CodeGroup>
      ```typescript TypeScript theme={null}
      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
      ```

      ```python Python theme={null}
      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
      ```

      ```sh cURL theme={null}
      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"
          }
        }'
      ```
    </CodeGroup>

    <Note>
      Sensitive custom fields, meaning any field of type `password`, can't be pre-defined. The API rejects them in `cfmap`.
    </Note>
  </Step>

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

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

      ```sh Connect Link theme={null}
      # 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
      ```
    </CodeGroup>

    See the [Connect quickstart](/docs/connect/managed-auth/quickstart/) for the full account connection flow, and [Connect Link](/docs/connect/managed-auth/connect-link/) if you don't run JavaScript in your frontend.
  </Step>
</Steps>

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

## API reference

<CardGroup cols={2}>
  <Card title="App Overrides" icon="sliders" href="/docs/connect/api-reference/list-app-overrides">
    List, create, retrieve, update, and delete app overrides
  </Card>

  <Card title="OAuth Clients" icon="key" href="/docs/connect/api-reference/list-oauth-clients">
    Manage custom OAuth clients through the API
  </Card>
</CardGroup>