auth

Exchange code + PKCE verifier for a workspace session.

Changed on

Single-use and atomically consumed: two concurrent redemptions of one code cannot both yield a session.

The result is an opaque bearer whose server-side row here carries everything the locked session model requires, plus its two bound extras: the requesting origin and the issuing transaction. It differs from a browser session ONLY in transport — presented in an Authorization header, never a cookie — which is why CORS runs without credentials mode and this instance's CSRF posture is untouched.

CLIENT-SIDE THE BEARER LIVES IN JS MEMORY ONLY: never a cookie, never localStorage or sessionStorage, gone on tab close.

post/api/v1/auth/workspace/redeem

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/auth/workspace/redeem
  • Auth: none required

Request body

codestring required
pkce_verifierstring required
originstring required

Response

The workspace session, disclosed once.

valuestring required

Keep it in JS MEMORY ONLY — never a cookie, never localStorage or sessionStorage. In-memory storage narrows the at-rest window; it is not non-stealability, and this contract does not sell it as such.

sessionstring required

A prefixed UUIDv7, e.g. org_0198….

originstring required
handoffstring required

A prefixed UUIDv7, e.g. org_0198….

idle_expires_atstring date-time required

RFC 3339 UTC, microsecond precision.

absolute_expires_atstring date-time required

RFC 3339 UTC, microsecond precision.

elevatedboolean

True when this redemption ELEVATED the session the step-up transaction was bound to instead of establishing a new one. session is then that same session's id and value is its ROTATED bearer — not a second session. The rotation is deliberate: a bearer stolen before an elevation must not become an elevated bearer after it.

environmentstring

A prefixed UUIDv7, e.g. org_0198….

window_expires_atstring date-time

RFC 3339 UTC, microsecond precision.

Changes

  • 54b2780eec85Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • f84a1cd8a05aRevision changes
    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status