Agent Access & Step-Up
The two registration paths, step-up rules, the 3-step verification handshake, and runtime challenge timing.
Two paths register an agent: synchronous (owner has an AstraSync account and a verified KYD) or asynchronous outreach (owner doesn't yet). Both end with a registered agent under the owner's authorising party. They differ in who initiates and how step-up is applied.
Step-up rules at registration
| Auth method | Step-up requirement |
|---|---|
| Crypto keypair | None — the keypair is the step-up. |
| API key (any) | Always required. POST /agents/register with API-key auth returns 202 pending_approval with a requestId; the owner is emailed a Sign-In-To-Accept link and a dashboard alert is emitted. The agent activates only on owner approval. Use sdk.register({ waitForApproval: true }) to block until the request resolves, or omit the flag and call sdk.pollRegistration(requestId) later. |
| KYD ID on account | Precondition for any API-key agent registration. Without it, the API key cannot register agents (returns 403 KYD_REQUIRED). |
| KYD-verified (passport + selfie) | Bumps owner trust score. Does NOT bypass step-up. |
The 3-step verification handshake
- Owner sets agent's PDLSS at registration. Fixed for that version — to change it, the owner uses Upgrade, which issues a new version with a new ASTRA-id and retires the old one. This is the agent's declared envelope.
- Merchant sets endpoint access policy at endpoint registration. Independent of any single agent — describes what the endpoint will accept from anyone.
- Per session: agent declares intended PDLSS for this call → merchant checks against endpoint policy → AstraSync confirms the agent is operating within its registered boundaries → approve + record. If outside endpoint policy: merchant denies + records. If within endpoint policy but outside the agent's registered boundaries: AstraSync tells merchant to deny + records.
Both agent and merchant have purposes; session intent must overlap with both envelopes for access to be granted.
Runtime challenge timing
The runtime challenge fires while verify-access runs — only on endpoints (or routes) that require it, or when the caller asks for it — never at registration. AstraSync POSTs a challenge and the agent must list the counterparty it is calling as pending.
- Agents run through a Workforce Guard checkpoint: for calls made through the checkpoint, the
checkpoint answers the challenge — you don't need an
apiEndpoint. Direct calls (not through the checkpoint) are challenged at the agent's own handler; with none, they fail the challenge. - Agents that answer challenges themselves: set
apiEndpointto the base URL of your handler (AstraSync appends/astrasync/challenge). Deploy the handler before the first call to an endpoint that requires the challenge.
apiEndpoint is part of the agent's version: to add or change it later, use Upgrade (a new
version with a new ASTRA-id; the old one is retired). If the challenge fails on an endpoint that
requires it, that call is denied — the agent record itself remains valid. Fix the handler and
retry. Full contract: Runtime Challenge.
Async outreach: register on someone else's behalf
When the owner doesn't yet have an account:
POST /api/agents/request-registration
{
"agentName": "Their agent",
"ownerEmail": "owner@example.com",
"agentDescription": "...",
"reason": "..."
}
→ 202 { "requestId": "uuid", "message": "..." }We email the owner. If they already have an account, the email links straight to a sign-in page that lands on the pending-approval queue. Otherwise it walks them through account + KYD + agent registration. Poll status:
GET /api/agents/request-registration/{requestId}
→ 200 {
"status": "pending" | "approved" | "denied" | "expired",
"agentId": "uuid | null",
"requestedAt": "...",
"lastEventAt": "..."
}Operational, machine-readable detail for agents (error codes, runtime challenge spec, tier unlock) lives at Agent Access.