Skip to content
alfe.aiDocs

Authentication

Every call to the Agent API uses the agent’s own API key as a bearer token. Alfe resolves the agent’s agentId and tenantId from that token, so you never pass those ids yourself, and 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 each route's path
});

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 most of the dashboard’s routes on the same host don’t. The voice and phone routes are the exceptions: they live under /voice/ and /mobile/ and also accept agent tokens.

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 an API key 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 self-service access as that agent, so 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, revoke it and issue a new one.

Next

Section titled “Next”