Aura Handoff API (REST)

Aura document URLs are stable, shareable links for browser-based document access. The Aura handoff endpoint is used after a trusted login flow has authenticated a user and needs to return that user to Aura with a short-lived, one-time code.

This endpoint is for authenticated SSO login surfaces and trusted application backends. Do not put user identity, bearer tokens, or handoff codes directly into searchable document URLs.

All requests require api-version: 1.0.

Endpoint Overview

Method	Path	Description	Required Permission
POST	/aura/auth/handoffs	Create a one-time Aura redirect URL for an authenticated SSO user	Read, Admin

Create Handoff

POST /aura/auth/handoffs
Content-Type: application/json
x-api-key: YOUR_API_KEY
api-version: 1.0
Authorization: Bearer <nomos-token>

{
  "returnUrl": "https://aura.bluecurve.io/acme/01H2VXDR3M4N5P6Q7R8S9T0UVW/01H2VXDR3M4N5P6Q7R8S9T0ABC?ct=application/pdf"
}

The returnUrl must be a canonical Aura document URL under the configured Aura base URI. It must contain the ct content-type query parameter and must not contain legacy aat access-ticket parameters.

Response

{
  "redirectUrl": "https://aura.bluecurve.io/auth/handoff?code=...&returnUrl=..."
}

Redirect the browser to redirectUrl. Aura redeems the code once, creates its own secure session, and sends the browser back to the original document URL.

Security Notes

• Aura document URLs remain stable and can be bookmarked or shared.
• The user opening the URL must still have access when Aura checks authorization.
• Handoff codes are opaque, short-lived, and one-time redeemable.
• The browser never needs a Public API key.
• Return URLs outside the configured Aura base URI are rejected.

Common Errors

Status	Meaning
400	Invalid or non-canonical Aura return URL.
401	Missing authenticated SSO context or invalid credentials.
403	API key does not have the required permission.

---

Next: Jobs API