Security

Security Challenge

When a request is suspicious, the agent redirects the client to /security-check. After solving, the platform issues a short-lived token and the agent sets a aura_passport cookie.

Overview

Challenge page performs a proof-of-work (PoW) puzzle in the browser.
On success, platform redirects back to your site with ?up_token=....
Agent verifies up_token, sets a passport cookie, then reloads the original URL (clean).

Legacy query flow

Older agents redirected with sensitive params: /security-check?license_key=...&return_url=.... This works but leaks information into URLs.

Opaque token flow (recommended)

New agents first call POST /api/challenge/init to obtain an opaque token. Then they redirect to: /security-check?token=....

Why this matters: it prevents leaking license_key and return_url into logs, analytics, and referrer headers.

Endpoints

POST /api/challenge/init

{
  "license_key": "UP_LIVE_...",
  "return_url": "https://example.com/checkout"
}

Success response:

{
  "status": "success",
  "token": "BASE64(iv + cipher + mac)",
  "ttl": 300
}

GET /security-check?token=...

Renders the challenge UI. The token is decrypted server-side using APP_KEY and validated with an HMAC. Token TTL is 300 seconds.

POST /security-check

Submits the PoW solution + telemetry. On success returns: {status:"success", redirect:"<return_url>?up_token=..."}.

Cookies

Agent sets aura_passport after verifying up_token.
Cookie uses Secure only when the agent detects HTTPS.
See Proxy & HTTPS for reverse-proxy setups.

Troubleshooting

Looping challenges: usually HTTPS/proxy detection or cookie blocked.
403 Invalid Challenge Token: expired token (TTL 300s) or mismatched APP_KEY across nodes.
Wrong return host: check APP_CHALLENGE_RETURN_HOST (or app.challenge_return_host).