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. Immutable thereafter. 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 at first verify-access, not at register. apiEndpoint is immutable post-registration, so the recommended deploy order is:

Deploy your agent endpoint first.
Register the agent against that endpoint URL.
First counterparty call triggers the challenge handshake.

If the challenge fails (endpoint unreachable / wrong response), the call is denied — but the agent record itself remains valid. Bring your endpoint up and retry.

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.

Agent Access & Step-Up

The two registration paths, step-up rules, the 3-step verification handshake, and runtime challenge timing.

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. Immutable thereafter. 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 at first verify-access, not at register. apiEndpoint is immutable post-registration, so the recommended deploy order is:

Deploy your agent endpoint first.
Register the agent against that endpoint URL.
First counterparty call triggers the challenge handshake.

If the challenge fails (endpoint unreachable / wrong response), the call is denied — but the agent record itself remains valid. Bring your endpoint up and retry.

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": "..." }

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.