Identity

The identity endpoints answer two questions: who is this agent? and who is this agent talking to? The first is resolved from the agent’s token; the second resolves a person or system on some external platform (a Slack user, a GitHub account, an email address) to a stable identity the agent can remember and reason about.

All examples use the @alfe.ai/agent-api-client.

Who the agent is

Returns the calling agent’s own identity context, decoded from its token.

identity.ts

const { agentId, tenantId } = await client.whoami();
// GET /agent/identity/whoami

{ "data": { "agentId": "agt_…", "tenantId": "…" } }

Both ids come from the token, so this is the canonical way for an agent to learn its own agentId at runtime. It’s one round-trip — cache the result rather than calling it per action.

Resolve who you’re talking to

Given a platform and a platform-specific id, resolve (or create) the matching identity and get back the permissions that identity carries.

const result = await client.resolveIdentity({
  provider: "slack",          // the platform the id comes from
  platformId: "U0123456789",  // the platform's own id for the person
  kind: "user",               // user | agent | service | bot | workspace
  displayName: "Dana Lee",    // optional, used when creating a new identity
});
// POST /agent/identity/resolve

{
  "data": {
    "identityId": "…",
    "status": "matched",
    "created": false,
    "permissions": ["chat:send", "agent:read"]
  }
}

identityId is null on a miss. permissions is a flat list of permission strings for the resolved identity; it comes back empty on a miss, so a runtime gate built on it fails closed.

Search identities

Find existing identities by free-text query, status, or a result limit.

const { identities } = await client.searchIdentities({
  q: "dana",
  limit: 20,
});
// GET /agent/identity/search

Read an identity’s context

Fetch the stored context for one identity by id.

const { context } = await client.getIdentityContext(identityId);
// GET /agent/identity/{identityId}/context

Managing an identity

The client also exposes methods to curate identities over time. Each takes an identity id and returns a small result object:

Method	Endpoint	Purpose
updateIdentity(id, fields)	POST /agent/identity/{id}/update	Update display fields (name, avatarUrl, timezone, locale).
addIdentityNote(id, args)	POST /agent/identity/{id}/notes	Attach a freeform note.
tagIdentity(id, args)	POST /agent/identity/{id}/tags	Add or remove a tag.
mergeIdentities(survivorId, args)	POST /agent/identity/{survivorId}/merge	Merge a duplicate into a survivor.
unmergeIdentity(id, args)	POST /agent/identity/{id}/unmerge	Reverse a merge.
getIdentityChangelog(id, opts)	GET /agent/identity/{id}/changelog	Read the audit trail of changes.
rollbackIdentity(id, args)	POST /agent/identity/{id}/rollback	Roll the identity back to an earlier version.

Write methods that change an identity take a changedBy actor ({ type, id, name? }) so every edit is attributable in the changelog.

Verifying a claimed identity

When someone claims to be a person the agent already knows, the agent can run a challenge-and-confirm flow over a verified channel (email or mobile):

const challenge = await client.requestIdentityVerification({
  claimedIdentityId: "…",
  requestingIdentityId: "…",
  requestingProvider: "slack",
  requestingPlatformId: "U0123456789",
  preferredChannel: "email",
});
// POST /agent/identity/verify/request

const outcome = await client.confirmIdentityVerification({
  claimedIdentityId: "…",
  verificationId: challenge.verificationId,
  phrase: "the code the person received",
});
// POST /agent/identity/verify/confirm

A successful confirm returns { verified: true, identityId }.

Next

• Memory — remember facts about the identities you resolve.
• Shared knowledge — org / team / project knowledge the agent can read and contribute to.