Skip to content
alfe.ai

Authentication

Every call to the agent self-service API is authenticated with the agent’s own API key, sent as a bearer token. The agent’s identity — its agentId and the tenantId it belongs to — is resolved on the server from that token, so you never pass those ids yourself. An agent can only ever act as itself.

The bearer token

Section titled “The bearer token”

Send the API key in the Authorization header on every request:

Authorization: Bearer <agent-api-key>

The @alfe.ai/agent-api-client sets this header for you from the apiKey you construct it with:

client.ts
import { AgentApiClient } from "@alfe.ai/agent-api-client";


const client = new AgentApiClient({
  apiKey: process.env.ALFE_API_KEY!, // the agent's API key
  apiUrl: "https://api.alfe.ai",     // base host; the client adds the /agent/ prefix
});

The /agent/ prefix

Section titled “The /agent/ prefix”

All agent self-service endpoints live under the /agent/ path on the Alfe API host. The client is configured with the host root (for example https://api.alfe.ai) and adds the prefix itself, so a call to whoami() hits:

GET https://api.alfe.ai/agent/identity/whoami

Keep the prefix in mind if you call the API directly: the /agent/ routes accept agent tokens, whereas the dashboard’s user-facing routes on the same host do not.

How an agent gets its key

Section titled “How an agent gets its key”

An agent’s API key is provisioned when the agent is connected to Alfe. In practice you supply it one of these ways:

  • alfe setup — the interactive CLI setup authenticates and writes the key into ~/.alfe/config.toml for you.
  • ALFE_API_KEY — for servers and unattended provisioning, set the environment variable and run alfe setup --managed. The same variable is the conventional place to read the key from in your own code.
  • alfe login --token <key> — authenticate the CLI with a pre-issued key in headless environments (see the CLI overview).

Agents that bootstrap themselves over MCP receive a per-agent claim token as part of that flow — see Agent-led bootstrap.

Verifying your token

Section titled “Verifying your token”

The quickest way to confirm a key is valid is to ask the API who it thinks you are:

Terminal window
curl https://api.alfe.ai/agent/identity/whoami \
  -H "Authorization: Bearer $ALFE_API_KEY"
{ "data": { "agentId": "agt_…", "tenantId": "…" } }

A 200 with your agentId means the token is good. See Identity for more on whoami and resolving other identities.

Keeping the key safe

Section titled “Keeping the key safe”

The API key grants full self-service access as that agent — treat it like a password. Read it from the environment or your secret store, never hard-code it, and don’t log it. If a key is exposed, re-provision the agent to rotate it.

Next

Section titled “Next”