Callers

A Caller is a verified end-user identity observed behind delegated Act-As traffic. Dome projects Callers from audit evidence so you can inspect their identity, verification methods, and attributed agent activity.

Overview

An agent is the workload. A caller is the person that workload acts for. Callers are the human side of delegated agents: your application sends the person's identity in X-Dome-Act-As, Dome verifies it against a verification provider, and Rules, Quotas, egress, and audit read the verified claims.

This page covers both halves of that entity:

• Verification. Create the OIDC and HMAC providers that prove who a caller is, and set the workspace floor that decides whether verified identity is required and which methods are allowed.
• The registry. Inspect the callers Dome has actually observed, and erase a projected record when a person must be forgotten.

Callers are projected from audit evidence, so a caller appears only after Dome accepts delegated traffic carrying a verified identity. Nothing here creates a caller by hand.

Interactive OAuth users are not added to the registry. Their identity and revocable access belong to the interactive grant that lets a person ride an agent through an MCP client. Refer to Identity Patterns.

Provider hierarchy

Verification providers can belong to an organization, tenant, or workspace. A workspace can see its own providers plus providers inherited from its tenant and organization.

Dome resolves one effective provider for each non-bound agent:

1. A required provider pins the method and provider and forces Act-As on. The broadest configured scope wins: organization, then tenant, then workspace.
2. Otherwise, an agent's explicit provider reference wins.
3. Otherwise, the agent's inline OIDC or HMAC material wins.
4. Otherwise, a default provider supplies missing material. The nearest configured scope wins: workspace, then tenant, then organization.

A nearest default with the wrong method fails closed. Dome does not fall through to a farther provider. Bound agents bypass this hierarchy because enrollment already established their identity.

Use required providers for enforceable baselines. Use defaults to reduce repeated configuration without overriding an explicit agent choice.

Requirements

Before you begin, authenticate to Dome and select a workspace.

Permissions

Per-agent Act-As configuration uses agent register permissions instead. Refer to Agents.

Create a verification provider

Create a workspace-scoped verification provider that delegated agents can share. Assign the returned provider ID when registering or updating an agent with --actas-provider / actas_provider_id. Agents can instead use an inherited provider or inline OIDC/HMAC material.

The method you pick here must match what your application puts in X-Dome-Act-As. Refer to Verification methods. How to send the header is on Pass identity for delegated agents.

In the dashboard, open Callers → Verification and add a provider.

OIDC

Use OIDC when end users sign in through an IdP and your application sends their JWT as X-Dome-Act-As.

dome workspace verification-providers create \
  --name workforce-oidc \
  --method oidc \
  --oidc-discovery-url https://auth.example.com

{
  "name": "workforce-oidc",
  "method": "oidc",
  "oidc_discovery_url": "https://auth.example.com"
}

POST /v1/workspaces/<workspace-uuid>/verification-providers
Content-Type: application/json

{
  "name": "workforce-oidc",
  "method": "oidc",
  "oidc_discovery_url": "https://auth.example.com"
}

Create an OIDC verification provider named "workforce-oidc" using the issuer https://auth.example.com.

Dome appends /.well-known/openid-configuration to the issuer base URL.

HMAC

Use HMAC when a trusted service constructs and signs the Act-As envelope with a shared secret.

dome workspace verification-providers create \
  --name internal-signer \
  --method hmac \
  --hmac-secret <shared-secret>

{
  "name": "internal-signer",
  "method": "hmac",
  "hmac_secret": "<shared-secret>"
}

POST /v1/workspaces/<workspace-uuid>/verification-providers
Content-Type: application/json

{
  "name": "internal-signer",
  "method": "hmac",
  "hmac_secret": "<shared-secret>"
}

Create an HMAC verification provider named "internal-signer" with my shared secret.

List verification providers

List the verification providers in the workspace. Widen the result to the visible organization and tenant chain when selecting an inherited provider.

dome workspace verification-providers list
dome verification-providers list --include-chain

{
  "name": "dome_verification_providers_list",
  "arguments": {}
}

GET /v1/workspaces/<workspace-uuid>/verification-providers

Delete a verification provider

Delete a verification provider when no agent should use it.

dome workspace verification-providers delete <provider-id>

{
  "provider_id": "<provider-id>"
}

DELETE /v1/workspaces/<workspace-uuid>/verification-providers/<provider-id>

Require verified identity

Update the workspace Act-As floor so every agent must present a verified end-user identity (every agent in the workspace behaves as a delegated agent at the edge), and optionally restrict which verification methods are allowed.

When the workspace requires verified Act-As:

• Every request must include a valid identity envelope.
• The verification method must be allowed by the workspace.
• An agent configured with actas_method=none is rejected.
• Invalid, expired, malformed, or unverifiable identity fails closed before authorization.

Agent settings can be stricter than the workspace floor, but cannot weaken it. An agent can require Act-As when the workspace does not, or narrow which verified identities it may present by group, email, or subject. Set per-agent options on Agents.

dome workspace actas update --required

dome workspace actas update --allowed-methods oidc,hmac

{
  "actas_required": true,
  "actas_allowed_methods": ["oidc", "hmac"]
}

PATCH /v1/workspaces/<workspace-uuid>/actas
Content-Type: application/json

{
  "actas_required": true,
  "actas_allowed_methods": ["oidc", "hmac"]
}

Require verified Act-As on every request in this workspace and allow only oidc and hmac.

Read the current floor with dome workspace actas get, dome_workspace_actas_get, or GetWorkspaceActAs.

Tightening allowed methods can strand agents that already use an excluded method. The dashboard's Verification tab previews which agents would start failing at the Gateway before you save. Review the configured method with dome agents get first when you change the floor from the CLI, MCP, or API.

Select default and required providers

Set provider selections independently at each scope. Update commands use full-replace semantics: an omitted selection clears that field.

# Nearest default wins: workspace > tenant > organization
dome workspace actas update --default-provider {{PROVIDER_ID}}
dome tenant actas update --default-provider {{PROVIDER_ID}}
dome org actas update --default-provider {{PROVIDER_ID}}

# Broadest requirement wins: organization > tenant > workspace
dome org actas update --required-provider {{PROVIDER_ID}}

Tenant selections accept tenant- or org-scoped providers. Organization selections accept org-scoped providers. Workspace selections accept any provider visible in the workspace's scope chain.

Provider reads are scope-aware:

dome verification-providers list --scope workspace --include-chain
dome verification-providers get {{PROVIDER_ID}} --scope org
dome verification-providers list --scope tenant

CLI and MCP provider writes currently target workspace scope. The dashboard's Callers → Verification tab manages workspace providers and workspace policy, and shows inherited tenant and organization policy read-only. Manage organization providers from Settings → Single Sign-On; an active SSO connection can create a matching org-scoped OIDC provider that Act-As can reuse. Tenant provider creation is not exposed in those customer surfaces yet.

Inspect callers

In the dashboard, open Callers. Search by subject or email, or filter by group, claim, or verification provider. Select a row to inspect:

• identity claims and every observed verification method
• first-seen and last-seen timestamps
• agents, models, and tools attributed to the caller
• lifetime and current-month activity

Current-month sections appear only when the caller had activity during the current UTC calendar month. Lifetime totals remain available independently.

You can read the same projection from the CLI or MCP:

# List callers in the active workspace
dome callers list

# Filter by a group and an exact claim
dome callers list --group support --attribute region=us

# Inspect one caller
dome callers get {{CALLER_ID}}

{
  "name": "dome_callers_get",
  "arguments": {
    "caller": "{{CALLER_ID}}"
  }
}

Erase a projected caller record

Caller erasure is a CLI and MCP compliance operation; the dashboard does not expose a delete action.

dome callers delete {{CALLER_ID}}

{
  "name": "dome_callers_delete",
  "arguments": {
    "caller": "{{CALLER_ID}}"
  }
}

Erasure removes the projected identity record and its per-agent activity rows. It does not delete the underlying audit evidence. If later delegated traffic carries the same verified identity, Dome creates the projection again.

Next steps

• Delegated agents to configure an agent to act for a caller and write claim-aware Rules
• Configure Act-As on an agent for method, required flag, provider, and allow-lists
• Pass identity for delegated agents from your application
• Identity Patterns to compare delegated Act-As with interactive OAuth
• Audit events to investigate the retained evidence behind caller activity