Connect to Diagrid

This guide shows you how to wire an application to Diagrid: point your Dapr SDK at the project endpoints, authenticate with the app's API token, and pick a connection option for the traffic Diagrid routes back to your app.

Unlike self-hosted Dapr where a sidecar runs alongside your application, Diagrid hosts the Dapr runtime centrally. Your apps use the standard Dapr SDKs to reach Diagrid endpoints over HTTP or gRPC — there is no sidecar to deploy on your end.

For the conceptual model behind projects, apps, and components, see Organizations and Projects, Application Identities, and Components.

What you need to connect

Every connection combines two pieces of information:

• Project endpoints — the HTTP and gRPC URLs your SDK calls. Shared by every app in the project.
• App API token — identifies and authenticates the calling workload. Issued per app.

The project provides the address; the app provides the credential.

Configure Dapr SDKs with environment variables

The Dapr SDKs read three environment variables at client initialization:

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

Default SDK behavior

If these variables are not set, the SDK falls back to http://localhost:3500 and localhost:50001, which target a local Dapr sidecar and will not reach Diagrid.

Retrieve the values

From the Diagrid Web Console:

• On the Projects page, open your project to copy the HTTP Endpoint and gRPC Endpoint.
• On the Apps page, open an app inside that project to 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 app get <your-app-id> --project <your-project-id>

Set the 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 dev/test, the Diagrid CLI's diagrid dev run command injects these environment variables for you, so you don't have to retrieve and export them manually.

Connect an app to your application

Every app has two parts that shape how it connects to Diagrid:

• API Token — authenticates all API requests from your application to Diagrid.
• App Connection (optional) — configures how Diagrid routes outbound requests back to your application endpoint.

From the app details page in the Diagrid Web Console, you can connect an app in three ways:

• Connect to terminal — streams inbound requests to your local terminal for inspection and testing. See diagrid listen.
• Connect to app via private tunnel — creates a local tunnel that routes Diagrid traffic to a port on your local machine using the Diagrid CLI. See Connect for Dev/Test.
• Connect to app endpoint — manually configures a reachable application endpoint URL (for example, https://your-app:port/). See diagrid app update.

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, actor invocations, or health checks from Diagrid. If your app doesn't run a server (a workflow worker, for example), leave the app connection unset. See When to leave the app connection unset.

Secure the application connection

When you configure a manual application endpoint, secure the connection so only Diagrid can call your application. Use an application token — a secret you choose, set with diagrid app update --endpoint-token or in the app's connection settings in the console:

• Authentication — provide a secret token in the app's application connection settings.
• Verification — Diagrid includes this token in the dapr-api-token HTTP header (or gRPC metadata) on every request it makes to your application.
• Implementation — your application code verifies that the incoming token matches the one configured in Diagrid.

Which secret the header carries

dapr-api-token is the header name in both directions, but it does not carry the same secret each way:

Direction	The header carries	Where the value comes from
Your application → Diagrid	The app's API token, the value you export as DAPR_API_TOKEN	Issued by Diagrid; read it with diagrid app get
Diagrid → your application	The application token	Chosen by you; set it with diagrid app update --endpoint-token

dapr-api-token carries a different secret each wayYour app sends its API token (DAPR_API_TOKEN) to the project endpoint. Calls from Diagrid come from the project's egress address and carry the application token you chose.

Do not reuse the value of DAPR_API_TOKEN as the application token. Diagrid never sends that value to your application, so a callback handler expecting it rejects every request.

Combined security

Pair application token verification with network-level allowlisting using the project's Egress Address (visible on the Diagrid Projects page or via diagrid project get).

Exposed endpoints

When using a manual endpoint, your application must be reachable from Diagrid. Allowlist the project's Egress Address in your network firewall or API gateway to permit Diagrid traffic.

What's next

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