link_agentauth
Link a standalone trust profile to an AgentAuth identity using a signed proof JWT and access token, transferring history and scores. After linking, authenticate exclusively with AgentAuth token.
Instructions
Link a standalone trust profile to an AgentAuth identity.
Provide your AgentAuth access_token, the public_key_hex you
originally registered with, and a signed_proof JWT proving you own
the standalone agent's private key. Your interaction history and scores
transfer to the AgentAuth identity. The standalone profile is updated to
reflect the AgentAuth source. This is a one-time, irreversible operation.
After linking, authenticate exclusively with your AgentAuth token — the public key will no longer be usable for authentication.
Canonical agent ID contract: after a successful link the canonical
agent_id is always the original standalone UUID. The AgentAuth UUID
is stored as agentauth_id in the profile's metadata and is also
returned in the response as agentauth_id. All historical scores and
interactions remain attached to the canonical standalone UUID.
The signed_proof JWT must be signed with the standalone agent's
Ed25519 private key (algorithm EdDSA) and contain the following
claims:
sub: yourpublic_key_hex(hex-encoded 32-byte public key)action: the literal string"link_agentauth"iat: issued-at Unix timestamp (must be within 300 seconds of now)
Example (Python)::
import jwt, time
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
private_key = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(private_key_hex))
signed_proof = jwt.encode(
{"sub": public_key_hex, "action": "link_agentauth", "iat": int(time.time())},
private_key,
algorithm="EdDSA",
)Args:
access_token: Valid AgentAuth bearer token identifying the target identity.
public_key_hex: Hex-encoded Ed25519 public key used during standalone registration.
signed_proof: JWT signed by the standalone agent's Ed25519 private key,
proving ownership of the key. Must contain sub, action, and
iat claims as described above.
dry_run: When True, validate everything but do not commit any
changes. Returns a preview of what would happen including current
scores. Defaults to False.
Returns:
On success: agent_id (canonical standalone UUID), canonical_agent_id
(same as agent_id), agentauth_id (AgentAuth UUID stored in
metadata), merged (bool), and a confirmation message.
On ``dry_run=True``: ``dry_run`` (``true``), ``would_link_agent_id``,
``agentauth_id``, ``current_scores``, ``interaction_count``,
``capabilities``, and ``message``.Error codes:
- invalid_input: malformed public_key_hex.
- proof_sig_invalid: JWT signature or content check failed.
- proof_expired: JWT iat is outside the 300-second window.
- key_not_found: no standalone agent registered with that public key.
- already_linked: the standalone profile is already linked to AgentAuth.
- authentication_failed: AgentAuth token invalid or expired.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| access_token | Yes | ||
| public_key_hex | Yes | ||
| signed_proof | Yes | ||
| dry_run | No |