API Mappings

Congratulations! You're ready to start using your Processes and let magic happen. But how can they work with your business? This is where API Mappings come in.

You can think of API Mappings as how your Processes interface with the world. It's how Unmeshed allows external entities to trigger and monitor Processes. Technically, it is done by creating uniquely named API endpoints to control the various Processes you've created.

Trigger modes

Process endpoints published via API Mappings can be triggered in three different modes:

Mode	Description
Async	The Process is started and the API call returns immediately with RUNNING status. This is useful for when you're expecting the Process to take a long time and are not interested in waiting for its completion.
Streaming	This API call is similar to async, except it keeps the connection open and streams completed steps as they're completed. This can be useful for debugging or when you'd like to follow execution on a step-by-step basis.
Synchronously	Starts the Process and does not return a response until the Process is completed. Useful in relatively short Processes or when the client requires to perform synchronous processing.

Video Overview: Unmeshed API Mappings

Creating API Mappings

To create an API mapping, you need to configure several key fields:

API Mapping Configuration

Required Configuration Fields

Field	Description
Endpoint	The endpoint name used in the URL path (/api/call/{name}). Must contain only alphanumeric values
Process Definition Namespace	The namespace where your process definition resides
Process Definition	The name of the process definition to execute when this endpoint is called
Version	The version of the process definition to use (defaults to "Latest")
Security	The authentication mechanism for the endpoint

Webhook URLs

Webhook URLs are the actual URL endpoints that invoke your API mapping. You can create multiple webhook URLs for a single API mapping definition, which is useful when you need different endpoints for different tools or users.

Webhook URLs Management

Types of Webhook URLs

Fixed URLs: Predefined, static endpoints with consistent paths

• Use case: When you need predictable, unchanging URLs
• Example: /api/call/sample_endpoint/first_fixed_url/fixed

Fixed URL Configuration

Dynamic URLs: Automatically generated endpoints with unique identifiers

• Use case: When you need unique, secure URLs for different clients
• Example: /api/call/sample_endpoint/ICU52F0nTX3sYMg92EHo/dPBrjvF5MS8g7YI8J0BO

Dynamic URL Configuration

Authentication

Unmeshed supports multiple authentication methods for API mappings:

Auth Method	Description
Preconfigured OAuth2.0 Options	Standard OAuth2.0 authentication for secure API access
Webhook	Anonymous access for users who have the URL
Default Authentication	Same auth configured for the Unmeshed UI access

Authentication Methods Explained

Preconfigured OAuth2.0 Options: Use standard OAuth2.0 authentication for secure API access. This requires clients to provide valid OAuth tokens when calling the endpoint.

Webhook: Provides anonymous access for users who have the specific webhook URL. This is useful for third-party systems that cannot send OAuth tokens but need to call your endpoint.

Default Authentication: Uses the same authentication mechanism configured for the Unmeshed UI access. This ensures consistency with your organization's authentication setup.

Webhook Authentication Use Case

When you set security to "Webhook", the endpoint allows anonymous access for users who have the specific webhook URL. This is particularly useful when configuring endpoints as webhooks for third-party systems that cannot send valid OAuth tokens. In such cases, you can implement custom validations within your process or router process to ensure the caller is legitimate.

Default Input Structure

When a process is invoked using an API mapping URL, Unmeshed automatically provides default input data:

{
  "__callerIp": [
    "1.1.1.1"
  ],
  "__webhook": {
    "authType": "WEBHOOK",
    "name": "first_fixed_url",
    "uniqueId": "first_fixed_url",
    "apiEndpoint": "sample_endpoint"
  }
}

Default Input Fields

Field	Description
__callerIp	Array of IP addresses from which the request originated
__webhook.authType	The authentication type used for the request
__webhook.name	The name of the webhook URL that was called
__webhook.uniqueId	The unique identifier of the webhook URL
__webhook.apiEndpoint	The API mapping endpoint name

This default input is automatically merged with any custom input you provide when calling the endpoint, making it available throughout your process execution.

Authentication Scenarios

Manage Complex Auth Scenarios

Unmeshed supports OIDC based auth servers. Support for SAML is coming soon. We also offer a built-in user password auth if you prefer to use that.

Once a user is authenticated, the corresponding claims from the user token is set to the process context which can be referred anywhere in the workflow.

Rate limiting

Rate limiting is a feature that is being built - if you need this soon, let us know and we accelerate this build.