About Custom Apps
Custom Apps in Serval allow you to integrate any third-party application that has an API, even if it’s not available as a pre-built integration. This feature enables you to extend Serval’s capabilities to work with your organization’s unique tools and services.
What the Custom App integration enables
| Capability | Description |
|---|
| Workflow Automation | Create custom workflows to interact with your integrated applications |
| API Proxying | Serval securely proxies API requests to your custom apps, handling authentication |
| Access Management | Manage access to your custom apps using Serval’s access policies |
Creating a Custom App in Serval
Follow these steps to create and configure a custom app integration:
Step 1: Navigate to Custom Apps
- In the Serval UI, go to the Available Apps section
- Scroll down to the bottom where you’ll find the Custom App option
- Click Connect to begin the setup process
A modal will appear allowing you to configure your custom app:
Fill in the following fields:
- 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
Click Connect to create the custom app.
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
Please refer to your specific third-party application’s documentation for detailed instructions on:
- 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 Custom App configuration in Serval
- Enter the new credentials (old credentials cannot be retrieved)
- Click Save to update the configuration
Your custom app is now connected and ready to use in Serval workflows!
Programmatic Access (API)
You can also create and manage Custom Apps programmatically using the Serval API. This is useful for:
- Automating the creation of Custom Apps as part of your infrastructure-as-code
- Building integrations that programmatically manage app connections
- Syncing Custom Apps from external systems
Understanding the Data Model
When using the API, it’s important to understand that Custom Apps 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 Custom App. You must also create an App Instance linked to the Custom Service. Only App Instances appear in your Apps list in Serval.
API Endpoints
