Verify an agent

An Authority runtime key is a project API key bound to one specific Agent principal. The binding is what makes the agent identity enforceable. A name, X-Keel-Agent-* header, or detected provider can help Keel label traffic, but none of those fields can establish an identity that a policy may hard-enforce.

This page is the canonical setup path for the Authority runtime key returned by the dashboard. Use the SDK documentation for provider-specific execution examples.

Before you start

You need:

access to the project in the Keel dashboard;
an active agent visible under Authority; and
a place to store a secret, such as your deployment platform’s secret manager.

Verification establishes the agent identity. It does not grant the agent any actions. Configure the agent’s allowed scope separately through Authority and Policies.

1. Issue the key from Authority

Open the project dashboard and choose Authority.

For an existing claimed agent:

Select the agent.
Choose Verify agent or Issue runtime key.
Give the key a recognizable name if the dialog asks for one.
Store the full value immediately. Keel returns the raw secret only in this one-time response.

For a new agent, choose Connect agent in Authority and run the generated setup command. The short-lived setup token creates or connects the agent and returns the same bound runtime-key result. Do not reuse an expired setup token.

Treat the runtime key like a production credential. Store it in a secret manager, do not commit it to source control, and do not paste it into logs or issue trackers. If it is exposed, revoke or rotate the bound credential before using the agent again.

2. Configure the runtime

The dialog returns the environment-variable name for this bound credential. The standard Connect agent flow uses KEEL_RUNTIME_KEY; an existing-agent verification flow may suggest an agent-specific name. Use the exact name shown by the dialog.


# Standard Connect agent flow
export KEEL_RUNTIME_KEY="keel_sk_your_agent_bound_key"

The variable name is a convention used by the setup flow; Keel authenticates the bearer token. A normal unbound project key can authenticate ordinary project API calls, but it cannot prove an Authority agent identity.

Keep the key on the server or worker that represents that agent. Do not expose it in browser code or send it from an untrusted client.

3. Verify the binding without a model call

Use the identity endpoint before sending provider traffic:


curl -sS "https://api.keelapi.com/v1/identity/whoami" \
  -H "Authorization: Bearer $KEEL_RUNTIME_KEY"

The response should include:


{
  "verified": true,
  "identity_state": "verified_agent",
  "agent_principal_id": "…",
  "agent_name": "…",
  "project_id": "…",
  "project_environment_type": "production"
}

This check resolves the active key and records that it was seen. It does not make a provider or model call.

If the key is not bound, revoked, expired, or belongs to another project, the endpoint fails with an authorization error. Do not treat a caller-supplied agent header as a fallback for this check.

4. Send the first governed request

Use the SDK provider wrappers or the provider proxy routes with the returned runtime-key variable as the bearer credential. The first governed request lets Keel record available framework and provider details for the verified agent. Those details are descriptive; the bound key remains the enforceable identity signal.

After the request, return to Authority and confirm that the agent shows as verified and that its credential has a recent last-seen time.

Key lifecycle

Stage	Meaning
Issued	A client API key was created for the project and returned once.
Bound	The key is linked to exactly one Authority agent.
Verified	A request authenticated with that key resolved to the bound agent.
Enforced	Policies and Authority grants may now use the verified identity.
Revoked	The credential can no longer establish that agent identity.

Decommissioning an agent revokes its active runtime credentials as part of the same Authority lifecycle operation. When rotating a credential, update the runtime’s secret before sending the next governed request and verify the new key with whoami.

Troubleshooting

`agent_identity_required`

The bearer token is a valid project credential but is not bound to an active Authority agent. Issue or connect the agent from Authority, then replace the runtime secret.

The agent is still only claimed

Claims and headers are attribution signals, not enforceable identity. Complete the one-time key setup and send a request through that key.

The key was exposed or lost

The raw value cannot be recovered from the dashboard after the one-time response. Revoke the exposed credential, issue a replacement, update the runtime secret, and run the whoami check again.

SDKs — Python and TypeScript provider wrappers.
Proxy Execution — provider-native HTTP routes.
Platform Surfaces — Runtime API versus dashboard Management API.
AI Permit-to-X — verified agents in bounded Permit workflows.