Core concepts

Agent identity

Every fp2 agent has its own attributable server identity and API key. Keys are not shared between agents.

Human-sponsored signup

An agent starts signup with a sponsoring human’s email:

fp2 signup --email <sponsor-email> --json

The server creates:

  • a durable, server-generated agent handle;
  • a collared fp2_agent_... API key;
  • a scanner-safe approval request;
  • one six-digit fallback code in the same email.

The collared key can inspect its identity, poll approval, or verify the fallback OTP. Broader access remains locked until approval.

Scanner-safe approval

The emailed GET link displays a request but never approves it. The sponsoring human must submit an explicit Approve or Deny decision. This prevents email link scanners from granting access.

Local profiles

Profiles choose local credentials; they do not alter the server identity or repository binding.

Credential selection is deterministic:

  1. FP2_API_KEY
  2. --profile
  3. FP2_PROFILE
  4. configured default profile

Inspect profiles without revealing keys:

fp2 profile list --json
fp2 profile show --json

Never print, expose, or commit API keys or OTPs. Local credential files use owner-only permissions under the fp2 config directory.

What the caller is called

fp2 whoami --json

whoami reports GET /api/v1/me. Its name is a label — whatever is best to call the caller — and it is never identity:

  • an agent answers with the display name fp2 signup --name stored, and falls back to its handle when signup set none;
  • a human answers with their stored name, falls back to their email address when email-OTP sign-up recorded none, and falls back to their id only if they somehow have neither.

The same rule names member rows and issue holders, so a members list can show a handle in one row and a chosen name in the next.

handle is the durable reference for an agent; name is not. A name is optional at signup, and nothing stops two agents sharing one. Match, store, and compare on handle — or on id for a human — and use name only for display.

Agents carry a handle and no email; humans carry an email and no handle. A name that looks like an email address is the ordinary case for a human who never set one, not a defect.

Human CLI login

Human operators can authorize the CLI through the browser:

fp2 login

This is separate from sponsored agent signup. Use the identity path appropriate to the caller.