Manage App IDs

An App ID is your application's identity inside a Catalyst project. Think of it like a username and password pair: the App ID name identifies your workload, and its API token authenticates every Dapr API call it makes to Catalyst. Each App ID also optionally configures how Catalyst routes traffic back to your app — pub/sub messages, input bindings, service invocations, and health checks.

Whether you're running a workflow, a durable agent, or a microservice, each workload binds to an App ID for identity, connectivity, and component scoping. The connectivity concepts page walks through how App IDs fit into the broader connection model.

Manage from the Catalyst console

Every operation on this page — creating App IDs, configuring app connections, health checks, body-size limits, and deleting — can also be done from the Catalyst Web UI at catalyst.diagrid.io.

What an App ID provides

Each App ID exposes:

API token — a bearer token used by your application to authenticate every Dapr API call to Catalyst.
App connection (optional) — how Catalyst reaches your application for inbound requests, via a reachable endpoint URL, a private tunnel, or streamed to the terminal.
Health checks — optional HTTP health probes against your application, with configurable path, interval, timeout, and failure threshold.
Runtime configuration — body-size limits, app protocol (HTTP or gRPC), channel timeouts, and an optional application token for securing callbacks.
Component scope — the set of components (state stores, pub/subs, bindings, etc.) that this App ID can use.

Create an App ID

# App ID without a reachable endpoint — good for apps that only call Catalyst APIs (e.g., workflow clients)
diagrid appid create my-appid --project my-project --wait

# App ID with a reachable app endpoint and an application token for callbacks
diagrid appid create my-subscriber \
  --project my-project \
  --app-endpoint https://myapp.myorg.com/ \
  --app-token xxxxxxxx \
  --wait

# App ID with a custom health check
diagrid appid create my-api \
  --app-endpoint https://myendpoint.io \
  --app-protocol http \
  --enable-app-health-check=true \
  --app-health-check-path "/healthz" \
  --app-health-probe-interval 5 \
  --app-health-probe-timeout 500 \
  --app-health-threshold 5 \
  --wait

# App ID with an increased max body size (default is the project-level value)
diagrid appid create my-large-payload-app --max-body-size 8Mi --wait

See diagrid appid create for the complete list of flags.

Connection options

When Catalyst needs to call your application (to deliver a pub/sub message, fire an input binding, or respond to a service invocation), it routes the request through the App ID's app connection. Choose the option that matches where your app runs — a reachable URL for production, a tunnel for local development, or streaming to your terminal for inspection:

Option	Use when	CLI
Connect to app endpoint	Your app is reachable over the network (public HTTPS, private endpoint).	Set `--app-endpoint` on `diagrid appid create` / `update`.
Connect via private tunnel	You are running the app locally for development.	`diagrid dev run` `--app-id my-app --app-port 9001`
Connect to terminal	You want to inspect inbound traffic without running app code.	`diagrid listen` `--app-id my-app`

See Connect for Dev/Test for the full local-development workflow.

Secure the application connection

When you configure a reachable app endpoint, secure the callback with an application token so only Catalyst can call your app:

diagrid appid update my-subscriber \
  --app-token "$(openssl rand -hex 32)"

See diagrid appid update for all updatable fields. Catalyst includes the token in the dapr-api-token HTTP header (or gRPC metadata) for every request it makes to your application. Validate the token in your app code and reject any request that doesn't carry it.

Combine with network allowlisting

For production deployments, pair the application token with network-level allowlisting using the project's egress address so that only Catalyst can route traffic to your app.

Health checks

Catalyst can monitor your application's health and stop routing traffic to unhealthy instances:

diagrid appid update my-api \
  --enable-app-health-check=true \
  --app-health-check-path "/healthz" \
  --app-health-probe-interval 5 \
  --app-health-probe-timeout 500 \
  --app-health-threshold 3

--app-health-probe-interval controls how often (in seconds) Catalyst probes the endpoint.
--app-health-probe-timeout sets the probe timeout in milliseconds.
--app-health-threshold is the number of consecutive failures before the app is considered unhealthy.

Body-size and channel limits

Each App ID inherits project-level limits for request body size and channel timeout. Override them per App ID when a workload has different requirements:

diagrid appid update my-upload-api \
  --max-body-size 16Mi \
  --app-channel-timeout-seconds 120

The maximum body-size value depends on your plan — see Plans & Support.

Inspect App IDs

# List all App IDs in the active project
diagrid appid list

# Get details for a specific App ID, including its API token and endpoints
diagrid appid get my-appid

# Stream logs from the App ID's Dapr runtime
diagrid appid logs my-appid --follow

See diagrid appid list, diagrid appid get, and diagrid appid logs. The logs command streams Dapr runtime logs from the Catalyst data plane so you can debug startup errors, component binding failures, and callback issues without leaving the terminal.

Update and delete App IDs

# Interactively edit an App ID's specification
diagrid appid edit my-appid

# Update a specific field
diagrid appid update my-appid --app-endpoint https://my-new-endpoint/

# Delete an App ID (this removes its API token and all component bindings)
diagrid appid delete my-appid --wait

See diagrid appid edit, diagrid appid update, and diagrid appid delete.

Use with workflows, agents, and distributed apps

Workflows — each workflow execution authenticates with an App ID's API token when calling the Workflow API. See Develop Durable Workflows.
Agents — agent applications bind to App IDs to leverage Dapr APIs for state, pub/sub, and service invocation. See Develop Agents.
Distributed applications — each microservice gets its own App ID, and services invoke one another by App ID name through the Service Invocation API. See the Dapr APIs guide.

Declarative management

App IDs can be managed declaratively with diagrid apply:

apiVersion: cra.diagrid.io/v1beta1
kind: AppID
metadata:
  name: my-appid
spec:
  appEndpoint: https://myapp.myorg.com/
  appProtocol: http
  enableAppHealthCheck: true
  appHealthCheckPath: /healthz
  maxBodySize: 8Mi

diagrid apply -f my-appid.yaml

See Declarative management for the full GitOps workflow, diagrid export patterns, and scoped API keys for CI.

What's next

Components — wire backing infrastructure to App IDs.
Connect to Catalyst — understand how App IDs fit into the overall connectivity model.
Observability — inspect App ID metrics, logs, and API calls.

What an App ID provides​

Create an App ID​

Connection options​

Secure the application connection​

Health checks​

Body-size and channel limits​

Inspect App IDs​

Update and delete App IDs​

Use with workflows, agents, and distributed apps​

Declarative management​

What's next​