Kinds
Locality is derived from kind. Local agents can use any capability. Remote agents are restricted to
read on server-managed items.
Schema
Authentication method
Agents authenticate with Ed25519 public-key sessions — the only agent auth method. The agent generates an Ed25519 keypair locally and uploads the public key during enrollment. Each working session is a short-livedabs_... token (15-minute TTL) issued in exchange for a signed challenge.
No long-lived secret is stored on disk. The private key lives in ~/.abadge/agents/<agent>.ed25519.jwk with 0600 permissions.
See Authentication for the full lifecycle.
To act on the management surface (organizations, profiles, items metadata, agents, permissions, audit, settings) from a script, use a personal API key (
abu_) instead. A personal API key resolves to a session identity and can never reach the agent access.* surface — it cannot read secret values.Token formats
Lifecycle
1
Create
POST /v1/agents registers the agent. public_key_session agents either provide publicKey directly or set issueBootstrapToken: true to receive an abe_... token.2
Enroll
For bootstrap-flow agents: the runtime generates an Ed25519 keypair and calls
POST /v1/agents/enroll with the bootstrap token and public key. The token is consumed.3
Exchange sessions
For each working session:
POST /v1/agents/{agentId}/sessions/challenge → sign → POST /v1/agents/{agentId}/sessions/exchange → receive abs_.... Repeat as the SDK’s background refresher does.4
Use
Pass
Authorization: Bearer abs_... to any agent access.* endpoint. The CLI and SDK do this automatically.5
Revoke
DELETE /v1/agents/{agentId} invalidates all active sessions and disables future authentication.Cascades
Revoking an agent revokes its active sessions and triggersagent.revoke_cascade audit entries for in-flight requests. Permissions are not deleted; they remain visible (and useless) until the agent is removed.
Removing an organization member cascades agent revocation for that member’s owned agents.