Develop with Dome

Develop wires an agent into product code against Agents, Gateways, and Resources already configured in Dome. Authenticate as an agent, call tools and models through a Gateway, pass identity for delegated agents when needed, and handle denials.

Refer to Architecture concept for the request path. Refer to Gateways concept for reachability.

Overview

Dome separates configuration from the client path. Connect and Govern define what an agent may reach and do. Develop covers the runtime client path: which credential to send, which Gateway URL to call, whether to attach act-as identity, and how to handle denials.

Point every client at a Gateway path that includes /gateways/{{GATEWAY_ID}}. A bare host fails closed.

The typical workflow is:

1. Authenticate with an agent key or short-lived JWT.
2. Route traffic to MCP and model endpoints on the Gateway.
3. Optionally pass identity for delegated agents when access depends on the person behind the agent.
4. Handle errors and denials from the gateway.

Runtime credentials

The gateway accepts either credential form as a bearer (or Anthropic x-api-key):

• Agent API key is a long-lived secret for services and hosted clients. Send it on every request, or exchange it for a JWT.
• Short-lived JWT is exchanged from the key through the Dome API when your runtime rotates credentials. Cache until expiry. Do not exchange on every call.

The management API accepts JWTs only. Store agent keys as secrets. Never send an upstream model or MCP credential from application code. The gateway injects configured credentials after authorization. Details are under Authenticate.

Gateway URL

Use one Gateway URL for each runtime client:

export DOME_AGENT_KEY="{{DOME_AGENT_KEY}}"
export DOME_GATEWAY_URL="https://{{GATEWAY_HOST}}/gateways/{{GATEWAY_ID}}"

Client bases append protocol paths to that URL:

Membership on the Gateway determines which tools and models the endpoint exposes. Grants and Rules still decide admission and actions. Build and verify URLs on Gateways. Call examples are under Route traffic.

Delegated identity on the wire

When the agent is delegated, every governed request carries verified end-user evidence in X-Dome-Act-As. Configure providers and the agent method in Delegated agents. Application code only attaches the header. It does not verify the claim. Refer to Pass identity for delegated agents.

Requirements

Before you begin:

• Register an agent, create its key, and grant it access to a Gateway that already has the tools or models you need as members
• Confirm Rules (and Guards or Quotas, if used) allow the calls you will make
• Set DOME_AGENT_KEY and DOME_GATEWAY_URL as shown in Gateway URL

Configure MCP servers, model connections, pools, credentials, and Gateway membership in Connect. Configure authorization and filtering in Govern.

Permissions

Runtime calls use the agent key and Cedar Rules, not workspace RBAC. Platform permissions apply when you manage agents, Gateways, or Rules in Connect and Govern.

Authenticate

Present the agent key on every runtime request. The gateway authenticates the agent before it evaluates Gateway admission or Cedar policy.

Use either credential form:

• Agent API key: Send the key directly for long-running services and hosted clients.
• Short-lived JWT: Exchange the key for a token when your runtime rotates credentials.

The gateway accepts both forms as bearer credentials. The management API accepts JWTs only.

Send the agent key

Send the key in the Authorization header for MCP and OpenAI-shaped requests:

Authorization: Bearer {{DOME_AGENT_KEY}}

Anthropic clients send their configured api_key as x-api-key on /v1/messages and /v1/messages/count_tokens. The gateway promotes it into the same agent identity pipeline.

x-api-key: {{DOME_AGENT_KEY}}
anthropic-version: 2023-06-01

Authorization takes precedence when both headers are present. Other runtime routes require bearer authentication.

Exchange the key for a JWT

Exchange the key against the Dome API, then cache the token until its expiry:

import os
import httpx

response = httpx.post(
    "https://{{DOME_API_HOST}}/v1/identity/token",
    json={
        "grant_type": "api_key",
        "api_key": os.environ["DOME_AGENT_KEY"],
    },
)
response.raise_for_status()

token = response.json()["access_token"]
expires_in = response.json()["expires_in"]

The default lifetime is 10 minutes. Refresh before expires_in. Do not exchange a token for every gateway call.

Route traffic

Send runtime traffic to the Gateway that contains the required tools or pools. Dome resolves the resource, authorizes the call, injects upstream credentials, and records the result.

Call MCP tools

Use an MCP Streamable HTTP client against the Gateway's /mcp endpoint:

import asyncio
import os

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    headers = {
        "Authorization": f"Bearer {os.environ['DOME_AGENT_KEY']}",
    }

    async with streamable_http_client(
        f"{os.environ['DOME_GATEWAY_URL']}/mcp",
        headers=headers,
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            catalog = await session.list_tools()
            print([tool.name for tool in catalog.tools])

            result = await session.call_tool(
                "github/list_issues",
                {"repo": "dome"},
            )
            print(result.content)

asyncio.run(main())

tools/list returns only tools in the selected Gateway that the agent may discover. tools/call evaluates authorization again for the requested tool.

MCP Streamable HTTP can return normal JSON or an SSE response. Keep the session open until the client consumes the complete result.

Call models

Point an OpenAI or Anthropic client at the Gateway. Set model to a Dome pool or connection name. The gateway preserves each client's native response shape and translates requests upstream only after resource resolution and authorization.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DOME_AGENT_KEY"],
    base_url=f"{os.environ['DOME_GATEWAY_URL']}/v1",
)

response = client.chat.completions.create(
    model="production",
    messages=[
        {"role": "user", "content": "Summarize the open incidents."},
    ],
)

print(response.choices[0].message.content)

stream = client.chat.completions.create(
    model="production",
    messages=[
        {"role": "user", "content": "Draft a short incident update."},
    ],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["DOME_AGENT_KEY"],
    base_url=os.environ["DOME_GATEWAY_URL"],
)

message = client.messages.create(
    model="production",
    max_tokens=512,
    messages=[
        {"role": "user", "content": "Summarize the open incidents."},
    ],
)

print(message.content[0].text)

with client.messages.stream(
    model="production",
    max_tokens=512,
    messages=[
        {"role": "user", "content": "Draft a short incident update."},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Choose the target by setting the request's model:

1. An exact pool name selects that pool.
2. An exact connection name selects that connection.
3. A provider model ID selects a matching connection.
4. A configured routing predicate can select a pool.
5. The workspace default pool handles the remaining request.

Application code chooses a logical target. Resolution order and match_when are on the Pools reference. Define membership, strategies, and failover on Pools and connections on Models.

Pass identity for delegated agents

When the agent is delegated, attach the human identity on each request. The gateway verifies it before Cedar, routing, per-user credentials, or backend forwarding uses it.

Send the evidence in X-Dome-Act-As on MCP, OpenAI, and Anthropic requests. Match the wire value to the agent's configured verification method. The method-to-header table is on Delegated agents. Prefer OIDC or bound identity for production traffic. Configure providers on Delegated agents.

Pass OIDC identity to MCP

Add the end-user token to the session headers:

headers = {
    "Authorization": f"Bearer {os.environ['DOME_AGENT_KEY']}",
    "X-Dome-Act-As": end_user_oidc_token,
}

Reuse the same headers for tools/list and tools/call. Discovery can include per-user credential advisories specific to that identity.

Pass OIDC identity to OpenAI

Create a client for the current user or pass the header per request:

client = OpenAI(
    api_key=os.environ["DOME_AGENT_KEY"],
    base_url=f"{os.environ['DOME_GATEWAY_URL']}/v1",
    default_headers={"X-Dome-Act-As": end_user_oidc_token},
)

Do not reuse a user-bound client across users. Pool clients by verified user only when token lifetime and isolation rules permit it.

Pass OIDC identity to Anthropic

Set the same header through the Anthropic client:

client = Anthropic(
    api_key=os.environ["DOME_AGENT_KEY"],
    base_url=os.environ["DOME_GATEWAY_URL"],
    default_headers={"X-Dome-Act-As": end_user_oidc_token},
)

The gateway keeps the agent and end user distinct. Agent authentication identifies the workload. Act-as evidence identifies the human represented by that workload.

Use identity at runtime

Verified claims populate principal.act_as for authorization and routing:

• principal.act_as.sub
• principal.act_as.email
• principal.act_as.roles
• principal.act_as.groups
• principal.act_as.claims.<key>

Per-user connections key credentials by the verified sub. If the user has not connected a credential, follow the provisioning response in Errors and denials.

The gateway forwards act-as identity upstream only when the connection explicitly configures an act-as-sourced header. Keep that egress choice in Connect.

Errors and denials

Separate authentication failures, missing user credentials, authorization denials, and upstream failures. Each requires a different application response.

Agent-facing prompt protocol

A missing per-user credential returns 401 Unauthorized before an LLM stream starts. Give the returned provision_url to the end user, then retry after completion.

Shared surfaces on every ingress:

• HTTP status: 401 Unauthorized
• Header: WWW-Authenticate: Bearer realm="dome", error="invalid_token", resource_metadata="<magic-link-url>"
• Body: a native permission error plus a dome.credential_required / dome_credential_required extension with provision_url and expires_at

The URL appears in the message text, the extension, and WWW-Authenticate so HTTP-aware tooling, Dome-aware clients, and SDKs that only render error.message can all recover. Per-user LLM requests also need a verified X-Dome-Act-As identity. Without act-as, the gateway returns 401 with a plain permission error and does not mint a magic link.

For MCP:

• tools/list includes _meta.dome.auth_required advisories (one entry per unprovisioned backend).
• tools/call sets error.data.type to dome.credential_required.

For OpenAI- and Anthropic-shaped routes, the body includes a top-level dome_credential_required sibling with connection, provision_url, and expires_at.

Do not mint or open the URL in a background service. Present it to the represented end user. Magic links are single-use and short-lived (10 minutes by default). If a link expires, the next call against the same connection mints a fresh one.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Per-user credential required for connection \"atlassian\". Provision your token at https://app.domesystems.ai/u/oauth/start?token=…",
    "data": {
      "type": "dome.credential_required",
      "provision_url": "https://app.domesystems.ai/u/oauth/start?token=…",
      "expires_at": "2026-04-29T18:30:00Z"
    }
  }
}

{
  "tools": [],
  "_meta": {
    "dome": {
      "auth_required": [
        {
          "backend_name": "atlassian",
          "provision_url": "https://app.domesystems.ai/u/oauth/start?token=…",
          "expires_at": "2026-04-29T18:30:00Z"
        }
      ]
    }
  }
}

{
  "error": {
    "message": "Per-user credential required for connection \"openai-prod\". Provision your token at https://app.domesystems.ai/u/creds/start?token=…",
    "type": "permission_error",
    "code": "dome.credential_required"
  },
  "dome_credential_required": {
    "connection": "openai-prod",
    "provision_url": "https://app.domesystems.ai/u/creds/start?token=…",
    "expires_at": "2026-04-29T18:30:00Z"
  }
}

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Per-user credential required for connection \"anthropic-prod\". Provision your token at https://app.domesystems.ai/u/creds/start?token=…"
  },
  "dome_credential_required": {
    "connection": "anthropic-prod",
    "provision_url": "https://app.domesystems.ai/u/creds/start?token=…",
    "expires_at": "2026-04-29T18:30:00Z"
  }
}

Authorization denial protocol

When the gateway denies a request, it returns a structured dome_authorization_denied extension alongside the native error body. The extension explains which rule fired so you can surface feedback in agent UIs and alert on the deciding policy.

• MCP — JSON-RPC error.data, with error.data.type = "dome.authorization_denied"
• LLM (OpenAI) — top-level dome_authorization_denied, plus error.code = "dome.authorization_denied"
• LLM (Anthropic) — top-level dome_authorization_denied. The Anthropic envelope has no code field

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "denied by rule: workspace/billing.policy0",
    "data": {
      "type": "dome.authorization_denied",
      "reason_code": "permission_denied",
      "reason": "denied by rule: workspace/billing.policy0",
      "depth": "deterministic",
      "determining_policy": "workspace/billing.policy0"
    }
  }
}

{
  "error": {
    "message": "denied by rule: workspace/billing.policy0",
    "type": "permission_error",
    "code": "dome.authorization_denied"
  },
  "dome_authorization_denied": {
    "reason_code": "permission_denied",
    "reason": "denied by rule: workspace/billing.policy0",
    "depth": "deterministic",
    "determining_policy": "workspace/billing.policy0"
  }
}

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "denied by rule: workspace/billing.policy0"
  },
  "dome_authorization_denied": {
    "reason_code": "permission_denied",
    "reason": "denied by rule: workspace/billing.policy0",
    "depth": "deterministic",
    "determining_policy": "workspace/billing.policy0"
  }
}

def explain_deny(body: dict) -> str | None:
    deny = body.get("dome_authorization_denied")
    if not deny:
        return None

    reason = deny.get("reason", "Request denied")
    policy = deny.get("determining_policy")
    return f"{reason} (policy: {policy})" if policy else reason

Allow responses carry no dome_authorization_denied field. Treat policy denials as final for the unchanged request. Show a safe reason to the user and record the request's activity or trace identifier.

Handle streaming failures

Authentication, act-as validation, per-user credential checks, and initial authorization run before the first model SSE event. These failures arrive as normal HTTP errors.

After streaming begins:

• Treat a broken connection as an incomplete response.
• Do not assume the gateway retried another model.
• Discard partial structured output unless your application validates it.
• Retry only when the operation is safe and your client can prevent duplicates.

Output filtering can buffer streamed text before release. Do not set client read timeouts so low that normal filter buffering appears as an outage.

Retry safely

Retry timeouts, connection failures, 429, and transient 5xx responses with bounded exponential backoff. Honor Retry-After when present.

Do not automatically retry 400, 401, or 403. Refresh an expired agent token, complete user provisioning, or change the denied request first.

Next steps

• Connect to attach resources, group them in Gateways, and configure routing
• Govern to authorize actions, assign Guards, and set Quotas
• Stream Live Events to trace calls, denials, latency, and model usage
• Agent Identity concept for keys, tokens, and act-as claims in more depth