Give an AI agent an identity

Create the agent's key

Generate an Ed25519 key pair where the agent runs. The script saves the private key to agent-key.pem and prints the public key, which is what you register.

// create-key.mjs
import { generateKeyPairSync } from "node:crypto";
import { writeFileSync } from "node:fs";

const { publicKey, privateKey } = generateKeyPairSync("ed25519");

// Keep this with the agent, and nowhere else.
writeFileSync("agent-key.pem", privateKey.export({ format: "pem", type: "pkcs8" }), { mode: 0o600 });

// Register this.
console.log(JSON.stringify(publicKey.export({ format: "jwk" })));

The script prints the public key as a JSON Web Key (JWK). You paste it into the console in a later step.

{ "kty": "OKP", "crv": "Ed25519", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" }

Name the agent

In the console, open Identity > AI Agents and select Register agent. Registration is a journey with the steps Name it, Its key, What it may do, Who it acts for, Review and Done.

On Name it, fill in these fields, then select Continue.

An agent that works on its own is an autonomous agent. The other kind, Acts for a person, is a delegated agent with an owner. How agent sign-in works explains the difference.

Register the agent's key

On Its key, under Where does the key come from?, select The agent already has one. Fill in these fields, then select Continue.

Choose what the agent may do

On What it may do, under On this platform, open Allow and choose the permissions the agent needs. Then select Continue.

The console says permission where these docs say capability. A capability can carry limits on the details of an action. An agent holds the permission itself through a role, as a person does. Limit what an agent may do shows how to give the role and set the limits.

Review and register

An agent that works on its own skips Who it acts for. On Review, check the Name, Kind and Key id, then select Register ticket-helper. The button carries the name you gave the agent.

The Done step says the agent is registered and shows its Agent id, which starts with agt_. Select Copy beside it. The agent ID is the agent's client_id.

export AGENT_ID=<your agent ID>

Select Open ticket-helper to go to the agent's page. Its Connect tab lists the same value as Client id, with the Token endpoint and a worked example.

Sign in and get an access token

The agent signs a short statement, called a client assertion, and sends it to the token endpoint. The assertion proves that the caller holds the agent's private key.

The assertion is a JSON Web Token (JWT) signed with the agent's key. It has these parts.

The body of the request is form-encoded.

// sign-in.mjs
import { createPrivateKey, randomUUID, sign } from "node:crypto";
import { readFileSync } from "node:fs";

const ISSUER = "https://acme.authfi.io";
const TOKEN_URL = `${ISSUER}/apis/regional/v1/ai/auth/token`;
const b64 = (v) => Buffer.from(JSON.stringify(v)).toString("base64url");

const privateKey = createPrivateKey(readFileSync("agent-key.pem"));
const agentId = process.env.AGENT_ID; // agt_…
const now = Math.floor(Date.now() / 1000);
const head = b64({ alg: "EdDSA", typ: "JWT", kid: "agent-key-1" });
const body = b64({ iss: agentId, sub: agentId, aud: TOKEN_URL, jti: randomUUID(), iat: now, exp: now + 120 });
const signature = sign(null, Buffer.from(`${head}.${body}`), privateKey).toString("base64url");

const res = await fetch(TOKEN_URL, {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: agentId,
    client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    client_assertion: `${head}.${body}.${signature}`,
    resource: `${ISSUER}/mcp`,
  }),
});
const token = await res.json();
console.log(token);

Replace https://acme.authfi.io with your project's issuer. AGENT_ID is the agent ID from the console, and agent-key-1 is the key ID you registered.

resource names the service the access token will be used at. Here it is the project's MCP gateway, the endpoint agents call tools through.

The token endpoint returns the access token.

{
  "access_token": "eyJhbGciOiJFZERTQSIs…",
  "token_type": "Bearer",
  "expires_in": 900,
  "agent_id": "agt_7f3a9c21",
  "type": "autonomous",
  "capabilities": ["read:tickets", "reply:tickets"]
}

capabilities lists the names of the permissions you allowed.

Use the access token

Send access_token as a Bearer credential in the Authorization header of each request the agent makes.

The access token lasts 15 minutes. When it expires, sign a new assertion and request another. An agent does not receive a refresh token.

An assertion is accepted once. Build a new one, with a new jti, for every request to the token endpoint.

To give the agent another capability later, open its Permissions tab and select Grant a permission.