Overview
Serval can connect to any third-party application that has an API, even if it’s not available as a pre-built integration. This lets you extend Serval’s capabilities to your organization’s unique tools and services.What connecting an application enables
| Capability | Description |
|---|---|
| Workflow Automation | Create workflows to interact with your connected applications |
| API Proxying | Serval securely proxies API requests to your applications, handling authentication |
| Access Management | Manage access to your applications using Serval’s access policies |
Connecting an application in Serval
Follow these steps to connect and configure an application:Step 1: Start a new connection
- In the Serval UI, go to the Available Apps section
- Scroll down to the bottom where you’ll find the Connect App option
- Click Connect to begin the setup process
Step 2: Configure basic app information
A modal will appear allowing you to configure your application:
- App Name: Enter the name of the application (typically the service name)
- App Domain: Provide the application’s domain URL. This allows Serval to automatically pull the logo for easy identification
- Instance Name (Optional): Add a brief instance name if needed to distinguish between multiple instances
Step 3: Configure authentication
After creating the app, you’ll be taken to the application configuration page, which looks similar to other pre-built integrations. To enable Serval to interact with your third-party app:- Select the API tab
- Choose your authentication method:
- OAuth: For OAuth-based authentication
- API Key: For traditional API key authentication
OAuth Configuration
API Key Configuration
- Enter your credentials and click Save
Obtaining third-party credentials
To complete the integration, you’ll need to obtain credentials from your third-party service:- For OAuth: Follow the OAuth app creation process in your third-party service’s developer documentation
- For API Keys: Generate an API key through your third-party service’s settings or developer portal
- Creating OAuth applications
- Generating API keys
- Setting appropriate permissions and scopes
Important notes
Security considerations
- Credentials are never returned to the frontend after being saved
- To update credentials, you must re-obtain them from the third-party service
Updating configuration
To change any authentication fields:- Go to the third-party service and grab the old credentials OR generate new credentials
- Return to the application configuration in Serval
- Enter the new credentials (old credentials cannot be retrieved)
- Click Save to update the configuration
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.
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.