Catalyst Connectivity Concepts

This guide explains how your apps actually connect to Catalyst: which endpoints they call, how they authenticate, and how Catalyst routes messages back to them.

Unlike self-hosted Dapr where sidecars run alongside your application, Catalyst hosts the Dapr runtime centrally. Your applications use standard Dapr SDKs to reach Catalyst endpoints over HTTP or gRPC — there's no sidecar to deploy on your end.

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 used by your application to call Catalyst Dapr APIs.
• gRPC Endpoint: The gRPC API endpoint used by your application to call Catalyst Dapr APIs.
• Egress Address: The source IP address used by Catalyst when it initiates outbound calls to your application (callbacks, subscriptions, service invocation responses).
• Ingress Address: The underlying infrastructure address (e.g., AWS Load Balancer) of the Catalyst data plane for your project.

These endpoints and addresses are shared by all applications within the project. You can find these values on the Catalyst Projects page within the project details (project filter/card view).

Network Allowlisting

If your application is behind a firewall, API gateway, or load balancer, you must allowlist the project's Egress Address to ensure Catalyst can deliver callbacks and service invocation requests to your application.

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

Configuring Dapr SDKs with Environment Variables

The Dapr SDKs connect to a Dapr API endpoint using a standard set of environment variables. When connecting to Catalyst, your application must be configured with the following three values, which combine the project endpoints and the App ID API token:

Environment Variable	Purpose	Source in Catalyst
DAPR_HTTP_ENDPOINT	HTTP endpoint the SDK uses to call Catalyst Dapr APIs	Project's HTTP Endpoint
DAPR_GRPC_ENDPOINT	gRPC endpoint the SDK uses to call Catalyst Dapr APIs	Project's gRPC Endpoint
DAPR_API_TOKEN	Authenticates and identifies your application to Catalyst	App ID's API Token

Default SDK Behavior

Dapr SDKs read these environment variables at client initialization. If they are not set, the SDK falls back to http://localhost:3500 and localhost:50001, which target a local Dapr sidecar and will not reach Catalyst.

Retrieving the Values

You can retrieve these values from either the Catalyst UI or the Diagrid CLI.

From the Catalyst UI:

• On the Projects page, open your project to view and copy the HTTP Endpoint and gRPC Endpoint.
• On the App IDs page, open an App ID within that project to view and copy its API Token.

From the Diagrid CLI:

# Get the project's HTTP and gRPC endpoints
diagrid project get <your-project-id>

# Get an App ID's API token
diagrid appid get <your-app-id> --project <your-project-id>

Setting the Environment Variables

Export the values in the environment where your application runs:

export DAPR_HTTP_ENDPOINT=<your-project-http-endpoint>
export DAPR_GRPC_ENDPOINT=<your-project-grpc-endpoint>
export DAPR_API_TOKEN=<your-appid-api-token>

Local Development

For local dev/test, the Diagrid CLI's diagrid dev run command automatically injects these environment variables for you, so you don't have to retrieve and export them manually.

Connect an App ID to your application

Every App ID has two parts that shape how it connects to Catalyst:

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

From the App ID details page in the Catalyst console, you can connect an App ID in three ways:

• Connect to terminal: Streams inbound requests to your local terminal for easy inspection and testing.
• Connect to app via private tunnel: Creates a local tunnel that routes traffic from Catalyst directly to a port on your local machine using the Diagrid CLI.
• Connect to app endpoint: Manually configures a reachable application endpoint URL (e.g., https://your-app:port/).

The Connect to app endpoint option is the manual callback configuration. Use this when your application is already hosted in a reachable environment and needs to receive pub/sub messages, input bindings, service invocations, or health checks from Catalyst.

Securing the Application Connection

When you configure a manual application endpoint, secure the connection so only Catalyst can call your application. This is done using an Application token:

• Authentication: Provide a secret token in the App ID's application connection settings.
• Verification: Catalyst will include this token in the dapr-api-token HTTP header (or gRPC metadata) for every request it makes to your application.
• Implementation: Your application code should verify that the incoming token matches the one you configured in Catalyst.

Combined Security

For the best security posture, combine the Application token verification with network-level allowlisting using the project's Egress Address.

Exposed Endpoints

When using a manual endpoint, your application must be exposed over the internet (or reachable by Catalyst). You must also allowlist the project's Egress Address in your network firewall or API gateway to permit Catalyst traffic.

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 data plane, while your workflow activities execute in your external application code.

Workflow Execution Model

The Dapr Workflow engine is embedded within the Catalyst data plane, and your workflow code uses an App ID's API token to establish the bidirectional 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

Built-in workflow store

Catalyst provides a built-in workflow store component for development and testing — see Managed Services.

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.

What's next

• Manage App IDs — create, update, and configure App IDs for your workloads.
• Dev & Test with the Diagrid CLI — connect local apps to Catalyst with tunnels and callbacks.
• Components — wire backing infrastructure to your App IDs.