Sign in
auth

Open a workspace handoff transaction.

Changed on

The browser edition of the RFC 8252 shape the CLI already uses: the front channel carries code and state ONLY, never the artifact.

Pre-authentication and CORS-readable for an allowlisted origin. A non-allowlisted origin is refused HERE, at the transaction — CORS controls what a browser may read, never what a token may do.

The viewing shell opens the returned authorization URL in a popup with noopener, so the return path is not window.opener: the popup's final redirect lands on a same-origin callback page of the viewing UI, which hands the result to the shell over a nonce-named BroadcastChannel.

post/api/v1/auth/workspace/start

Request

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

Request body

originstring required

The requesting UI origin. Must be allowlisted, or the transaction refuses.

redirect_uristring required

The exact pre-registered callback. Its authority IS the allowlist entry: a callback that does not live at the consented origin is not the consented code.

pkce_challengestring required

S256 challenge (RFC 7636). Plain is not accepted.

purpose'establishment' | 'step-up' required
sessionstring

A prefixed UUIDv7, e.g. org_0198….

operationstring

Step-up only, with session: the EXACT operation being elevated, so an elevated consent cannot be replayed against a different one.

environmentstring

A prefixed UUIDv7, e.g. org_0198….

key_setstring[]

Step-up only, where the operation is key-scoped: the enumerated key set the consent covers.

Response

The transaction's opaque state and its expiry.

handoffstring required

A prefixed UUIDv7, e.g. org_0198….

statestring required

Crosses the front channel. The artifact never does.

expires_atstring date-time required

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