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

# Connect a Custom Application

> Connect any application with an HTTPS API to Serval - even apps that aren't in the catalog - and use it in workflows with authentication handled for you.

## About custom applications

Serval can connect to any application that exposes an HTTPS API, even if it isn't in the [integration catalog](/sections/integrations/overview). You create the application once, store its API credentials with Serval, and from then on workflows can call its API with authentication injected automatically - the same pattern the native integrations use, pointed at your own tool.

Custom applications carry the **Access** and **Workflows** capabilities: workflows can call the app's API, and you can manage access to the app (resources, roles, and access policies) just like any other connected application.

**Authentication:** an API key or token (sent in a header you choose), or OAuth 2.0 client credentials (Serval exchanges a Client ID and Secret for tokens automatically). Browser-based "sign in with..." OAuth flows are not supported for custom applications - see the gotchas below.

**Data sync:** on demand. Workflows call the app's API when they run; there are no background syncs for custom applications.

## What a custom application enables

| Capability          | Description                                                                                                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow automation | Workflows (and Catalyst) call the app's API through Serval's built-in HTTP API request action - the workflow specifies what to do, and Serval fills in the base URL and authentication. |
| Secure API proxying | Credentials are stored encrypted, never shown back in clear text, and injected server-side on every request. Workflow authors never see or handle them.                                 |
| Access management   | Define the app's resources and roles, and manage access to them with Serval's access policies and requests - the same as any catalog integration.                                       |
| Multiple instances  | One application definition can have multiple instances (for example, a production and a sandbox tenant), each with its own credentials.                                                 |

## Get your credentials

Credentials come from the application you're connecting - check its developer or admin documentation for one of these:

* **An API key or token** - most tools issue these from a settings or developer page. Note which header the tool expects (a Bearer token, Basic auth username/password, an X-API-Key header, or a custom header name - Serval supports all four).
* **OAuth client credentials** - a Client ID and Client Secret plus the token endpoint URL, usually listed in the tool's API documentation. This is the machine-to-machine variant of OAuth (no browser sign-in).

Also note the API's **base URL** (for example, [https://api.example.com](https://api.example.com)) - the root URL for API requests, without any path.

## Connect in Serval

Connecting happens in two stages: create the application, then configure how it authenticates.

### Create the application

<Steps>
  <Step title="Open the catalog">
    In your team workspace, go to **Integrations → Connect new**. The **Connect an app** card is the first card in the grid - anything you've typed in the search box pre-fills the application name.
  </Step>

  <Step title="Fill in the application details">
    Click the card to open the **Connect an application** dialog:

    * **Application Name** (required) - typically the tool's name.
    * **Domain** (required) - the company's web domain (for example, "tool.com"), entered without a scheme; the field shows the "https\://" prefix for you. Serval uses it to fetch the app's logo automatically.
    * **Instance Name** (optional) - "This name helps distinguish multiple instances of the same app."
  </Step>

  <Step title="Create">
    Click **Create**. Serval creates the application and takes you straight to its page. If an application with the same service and instance name already exists, you'll see "an app for this service with this name already exists" - pick a different instance name.
  </Step>
</Steps>

### Configure API authentication

On the application's page, open the **API Integration** section ("Connect this application to an external API using an API key or OAuth credentials.") and choose an **Authentication Method**:

<Tabs>
  <Tab title="API Key">
    "Connect using an API key or token."

    <Steps>
      <Step title="API Base URL (required)">
        The root URL for API requests, without any path - for example, [https://api.example.com](https://api.example.com). Must start with https\://.
      </Step>

      <Step title="Add your authentication header(s)">
        Each header card has an **Authorization Method** selector with a live preview of the header Serval will send:

        * **Bearer Token** - paste your token; sent as an Authorization header with the "Bearer" prefix.
        * **Basic Auth** - enter the **Username** and **Password**; "Your username and password will be base64-encoded automatically."
        * **X-API-Key** - paste your key; sent as an X-API-Key header.
        * **Custom Header** - set the **Custom Header Name** (for example, "X-Custom-Auth") and the **Header Value** - any header name the tool expects.

        Use **Add Header** if the API needs more than one authentication header.
      </Step>

      <Step title="Save">
        Click **Save Credentials**. A green **Connected** badge appears once the credentials are stored.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OAuth Credentials">
    "Connect using a Client ID and Secret." This is the OAuth 2.0 client credentials grant - Serval mints and refreshes access tokens for you.

    <Steps>
      <Step title="API Base URL (required)">
        The root URL for API requests, without any path. Must start with https\://.
      </Step>

      <Step title="Token URL (required)">
        "The OAuth token endpoint - usually found in your API provider's developer docs." For example, [https://api.example.com/oauth/token](https://api.example.com/oauth/token). Must start with https\://.
      </Step>

      <Step title="Client ID and Client Secret (required)">
        "Found in your OAuth application or API settings." After saving, the secret is shown masked (its last four characters) with a **Replace** button - it is never displayed in full again.
      </Step>

      <Step title="Scopes (optional)">
        Specify the OAuth scopes needed for this integration, if the API requires them.
      </Step>

      <Step title="Save">
        Click **Save Credentials**. A green **Connected** badge appears once the credentials are stored.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  Saved secrets are encrypted and never returned to the screen - you'll see a masked value with a **Replace** button. To rotate a credential, click **Replace** and paste the new value; leaving a stored secret untouched while editing other fields keeps it unchanged. To remove authentication entirely, use **Clear Credentials** (it asks for confirmation).
</Note>

## How workflows use it

Once credentials are saved, workflows call the application through Serval's built-in **HTTP API request** action. The workflow (or Catalyst, when it builds one for you) specifies the request - the path, method, and any parameters - and Serval automatically applies your configured base URL and injects the stored authentication. Workflow authors never handle credentials, and requests only ever go to the base URL you configured.

## Verifying the connection

Custom applications don't have the prebuilt health checks that catalog integrations ship with. To confirm everything works end to end:

1. Check for the green **Connected** badge in the API Integration section - it confirms the credentials are stored.
2. Run a quick test workflow that makes a simple read request against the API (your Serval team or Catalyst can set one up in a couple of minutes).

A successful test request proves the base URL, authentication, and the app's permissions all work together.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="HTTPS is required everywhere">
    The API Base URL and Token URL must start with https\:// - the form and the backend both reject anything else. Plain http\:// APIs cannot be connected.
  </Accordion>

  <Accordion title="Browser-based OAuth sign-in is not supported">
    Custom applications support header-based credentials and the OAuth client credentials grant only. If a tool's API can only be accessed through a browser "sign in and approve" flow (authorization code OAuth), it can't be connected as a custom application - contact **[support@serval.com](mailto:support@serval.com)** about a native integration.
  </Accordion>

  <Accordion title="Enter the base URL without a path">
    The API Base URL should be the API's root (for example, [https://api.example.com](https://api.example.com)), not a full endpoint path. Workflow requests supply the path - if the base URL already contains part of the path, requests can end up doubled or misrouted.
  </Accordion>

  <Accordion title="The name pairing must be unique">
    Creating an application with the same name and instance name as an existing one fails with "an app for this service with this name already exists". Use the **Instance Name** field to distinguish multiple instances of the same tool.
  </Accordion>

  <Accordion title="Editing a multi-header setup means re-entering every header">
    With multiple authentication headers, changing, adding, or removing one header while leaving others untouched is rejected with "Please re-enter all credentials when making changes. Click 'Replace' on each existing header to update it." Have every header's value on hand before editing. Each header name can also be used only once - duplicates are rejected.
  </Accordion>

  <Accordion title="Secrets can be replaced but never viewed">
    After saving, credentials display as a masked value with the last four characters visible. There is no way to reveal a stored secret - if you've lost the original, generate a new one in the third-party tool and click **Replace** in Serval.
  </Accordion>

  <Accordion title="A workflow call fails with an authentication error">
    Re-check the header type against the tool's API documentation - the most common mismatch is a token pasted as a Bearer Token when the API expects X-API-Key (or vice versa), or a missing second header on APIs that require two. The **Authorization Method** preview in the form shows exactly what Serval will send.
  </Accordion>
</AccordionGroup>

***

## Programmatic access (API)

You can also create and manage applications programmatically using the Serval API. This is useful for:

* Automating the creation of applications as part of your infrastructure-as-code
* Building integrations that programmatically manage app connections
* Syncing applications from external systems

### Understanding the data model

When using the API, it's important to understand that applications consist of two separate resources:

* **Custom Service**: Represents the third-party application definition (e.g., "Internal HR System"). It stores the service name and domain for branding purposes.
* **App Instance**: Represents a specific installation/connection of a service that appears in your Apps list. Each Custom Service can have multiple App Instances.

<Warning>
  **Important:** Creating a Custom Service alone does **not** create a usable application. You must also create an App Instance linked to the Custom Service. Only App Instances appear in your Apps list in Serval.
</Warning>

When you create an application through the UI, Serval automatically creates both resources for you. When using the API, you must create both separately.

### API Endpoints

<CardGroup cols={2}>
  <Card title="Custom Service API" icon="cube" href="/api-reference/custom-service-api/create-custom-service">
    Create, read, update, and delete Custom Services (the underlying app definition).
  </Card>

  <Card title="App Instance API" icon="plug" href="/api-reference/app-instance-api/create-app-instance">
    Create App Instances linked to Custom Services using the `customServiceId` parameter.
  </Card>
</CardGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with connecting your application.