Skip to main content

Catalyst Connectivity Concepts

When hosting your applications with Catalyst, understanding how your workloads connect to the platform and how Catalyst manages Dapr resources on your behalf is essential. This guide explains the key concepts you need to know when building with Catalyst.

Projects and App IDs: The Foundation of Catalyst Connectivity​

To connect your application to Catalyst, you need two pieces of information that work together:

Catalyst Projects​

A Catalyst Project is the top-level container that provides the network endpoints for connecting to Catalyst's managed Dapr runtime. Each project exposes:

  • HTTP Endpoint: The HTTP API endpoint for Dapr operations
  • gRPC Endpoint: The gRPC API endpoint for Dapr operations

These endpoints are shared by all applications within the project and represent the entry point to Catalyst's infrastructure.

App IDs​

App IDs belong to a Catalyst project and represent individual application workloads. Each App ID provides a unique authentication token that identifies and authorizes your application when making requests to the Catalyst endpoints

The Connection Relationship​

To connect your application to Catalyst, you need both pieces of information:

  1. Project Endpoints (from your Catalyst project): These tell your application where to connect—the HTTP and gRPC endpoints that route to Catalyst's Dapr runtime
  2. App ID API Token (from an App ID within that project): This tells Catalyst who is making the request and provides authentication

Think of it this way: the project provides the address (endpoints), and the App ID provides the credentials (API token). Your application uses the project's endpoints to reach Catalyst, and includes the App ID's API token in each request to authenticate and identify itself.

Multiple App IDs can exist within a single project, each with its own API token. This allows you to:

  • Separate authentication and access control per application
  • Scope components and resources to specific App IDs
  • Maintain isolation between different workloads while sharing the same project infrastructure

App IDs: Your Connection to Catalyst​

An App ID is your application's identity within a Catalyst project. Each App ID represents an externally-hosted application workload and provides the API token needed to authenticate API requests to Catalyst's hosted Dapr runtime. App IDs work in conjunction with your project's endpoints to establish the complete connection to Catalyst.

App ID Overview

Why App IDs Matter in Catalyst​

Unlike self-hosted Dapr where sidecars run alongside your application, Catalyst hosts the Dapr runtime centrally. App IDs enable your applications—whether they're workflows, agents, or distributed microservices—to securely connect to Catalyst's managed Dapr APIs without requiring you to deploy or manage Dapr sidecars.

Each App ID includes:

  • API Token: Used to authenticate all API requests from your application to Catalyst
  • App Connection (optional): Configures how Catalyst routes outbound requests back to your application endpoint

Connecting Workflows, Agents, and Apps​

App IDs are the common thread that connects all your Catalyst workloads:

  • Workflows: Each workflow execution authenticates using an App ID's API token when calling the Workflow API
  • Agents: Agent applications use App IDs to connect to Catalyst and leverage Dapr APIs for state, pub/sub, and service invocation
  • Distributed Apps: Microservices use App IDs to discover and invoke each other via the Service Invocation API

All three workload types use the same App ID mechanism, providing a consistent security and connectivity model across your Catalyst project.

Workflows in Catalyst​

Catalyst's Workflow API enables long-running, stateful, and fault-tolerant business processes. When you host workflows with Catalyst, the workflow orchestration engine runs as part of the Catalyst dataplane, while your workflow activities execute in your external application code.

Workflow Execution Model​

The Dapr Workflow engine is embedded within the Catalyst dataplane, and your workflow code uses an App ID's API token to establish the bi-drectional stream between the workflow engine and your application code.

Workflow Components​

Workflows require a workflow store component (such as a database) to persist execution state. In Catalyst, you create components that connect to your infrastructure, and these components are scoped to specific App IDs. This allows you to:

  • Use different workflow stores for different applications
  • Apply resiliency policies specific to workflow operations
  • Control access to workflow infrastructure per App ID
Catalyst also provides a built-in workflow store component for development and testing purposes.

Agents in Catalyst​

Agents are autonomous applications that use Catalyst's Dapr APIs to interact with workflows, other agents, and distributed services. Agents leverage App IDs to authenticate and connect to Catalyst, enabling them to:

  • Subscribe to pub/sub topics for event-driven behavior
  • Maintain state across agent interactions
  • Invoke workflows or other services via Service Invocation
  • Respond to input bindings for external event triggers

Agent Connectivity​

Agents use App IDs with App Connections configured, allowing Catalyst to route messages and invocations back to your agent application. This bidirectional connectivity enables agents to both initiate actions (via API calls) and respond to events (via subscriptions and bindings).

Distributed Applications in Catalyst​

Distributed applications in Catalyst use multiple App IDs—one for each microservice—to enable service-to-service communication. The Service Invocation API allows services to discover and invoke each other using App IDs as service identifiers.

Service Discovery and Invocation​

When Service A needs to call Service B, it uses Service B's App ID in the invocation request. Catalyst handles:

  • Service discovery (resolving App IDs to endpoints)
  • Secure routing between services
  • Resiliency and retry policies
  • Observability across service boundaries

This model eliminates the need for service mesh configuration or manual endpoint management, as Catalyst manages service discovery and routing based on App IDs.

Connecting Infrastructure to App IDs​

Components are Catalyst resources that connect backing infrastructure services (databases, message brokers, etc.) to your App IDs. Components enable the Dapr APIs to perform their work—for example, a State API call requires a state store component, and a Pub/Sub API call requires a pub/sub component.

Component Scoping​

Components are scoped to App IDs, meaning you control which applications can access which infrastructure resources. This scoping model provides:

  • Access Control: Limit which App IDs can use specific components
  • Multi-tenancy: Different applications can use different infrastructure instances
  • Security: Isolate sensitive infrastructure resources to specific App IDs

Resiliency Policies​

When creating components, you configure resiliency policies that apply to operations between your App IDs and the backing infrastructure. These policies include:

  • Timeout: Prevents long-running operations from hanging
  • Retry: Automatically retries failed operations with exponential backoff
  • Circuit Breaker: Prevents cascading failures by temporarily stopping requests to failing infrastructure

These policies are enforced by Catalyst's Dapr runtime, meaning your application code doesn't need to implement resiliency logic—Catalyst handles it automatically based on component configuration.

Why These Concepts Matter for Catalyst Hosting​

When you choose Catalyst for hosting, you're leveraging a managed Dapr runtime rather than self-hosting Dapr sidecars. Understanding these concepts helps you:

  1. Secure Connectivity: App IDs provide the authentication mechanism for all Catalyst API calls, replacing the need to manage Dapr sidecar certificates and mTLS configuration across multiple clusters.

  2. Infrastructure Abstraction: Components abstract your infrastructure dependencies, allowing you to change backing services without code changes while Catalyst manages the connectivity

  3. Consistent Patterns: Whether building workflows, agents, or distributed apps, App IDs provide a unified connection model across all Catalyst workloads in a project

  4. Observability and Resiliency: Catalyst provides built-in observability and configurable resiliency policies that apply automatically to your App ID operations, without requiring instrumentation in your code

By understanding App IDs as your connection mechanism and components as your infrastructure abstraction layer, you can effectively leverage Catalyst's managed Dapr runtime to build and host workflows, agents, and distributed applications.