Skip to main content

​
About custom applications

Serval can connect to any application that exposes an HTTPS API, even if it isn’t in the integration catalog. 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

​
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) - 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

1

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

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.”
3

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.

​
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:
“Connect using an API key or token.”
1

API Base URL (required)

The root URL for API requests, without any path - for example, https://api.example.com. Must start with https://.
2

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

Save

Click Save Credentials. A green Connected badge appears once the credentials are stored.
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).

​
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

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.
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 about a native integration.
The API Base URL should be the API’s root (for example, 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.
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.
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.
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.
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.

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

Custom Service API

Create, read, update, and delete Custom Services (the underlying app definition).

App Instance API

Create App Instances linked to Custom Services using the customServiceId parameter.
Need help? Contact support@serval.com for assistance with connecting your application.