Mint a throwaway, auto-reaped ephemeral identity + token for automated UI validation (dev-gated;

POST

/v1/dev/agent-session

const url = 'http://localhost:8080/v1/dev/agent-session';
const options = {
  method: 'POST',
  headers: {'X-Quasar-Dev-Key': 'example', 'Content-Type': 'application/json'},
  body: '{"role":"user","ttl_seconds":1800}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

use serde_json::json;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "http://localhost:8080/v1/dev/agent-session";

    let payload = json!({
        "role": "user",
        "ttl_seconds": 1800
    });

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("X-Quasar-Dev-Key", "example".parse().unwrap());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.post(url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request POST \
  --url http://localhost:8080/v1/dev/agent-session \
  --header 'Content-Type: application/json' \
  --header 'X-Quasar-Dev-Key: example' \
  --data '{ "role": "user", "ttl_seconds": 1800 }'

Registered ONLY when QUASAR_DEV_AGENT_AUTH=1; absent the flag the route does not exist (404), and the control plane refuses to boot with the flag set while QUASAR_ENV=production. Auth is the per-boot dev key (written to the container log and /run/quasar/dev-agent-key), not a bearer token. Response is shape-compatible with POST /v1/auth/login so every existing client path works unchanged. The minted identity is a REAL user row with a real token — server-side role enforcement is untouched — and is deleted (with its sessions and device bindings) when its TTL lapses. Amendment 33: served only over TLS (the HTTPS listener, or a proxy named in QUASAR_TRUSTED_PROXIES that forwards X-Forwarded-Proto: https) or to a loopback peer, unless QUASAR_DEV_AGENT_INSECURE_HTTP=1. Any other request → 401 unauthorized before the key is compared.

Parameters

Header Parameters

X-Quasar-Dev-Key

required

string

The per-boot dev secret. Wrong or missing → 401 with no message/timing distinction.

Request Body

application/json

object

role

Role=admin mints a REAL admin (same enforcement path); the server logs it at WARN with the source address.

string

default: user

Allowed values: user admin

ttl_seconds

Identity lifetime. Default 30 min, hard cap 8 h. The token TTL is clamped to this — a token cannot outlive its user.

integer

default: 1800 >= 60 <= 28800

Responses

200

Ephemeral identity minted (login-shape + storage_keys).

application/json

object

access_token

required

The only credential ever returned — the identity’s password is random and never exposed.

string

token_type

required

string

Allowed values: Bearer

expires_at

required

Token AND identity expiry; the reaper deletes the user at/after this instant.

string format: date-time

user

required

object

required

string format: uuid

email

required

string format: email

username

required

string

role

required

string

Allowed values: user admin

created_at

Present on /v1/me + register; omitted from the login user.

string format: date-time

storage_keys

required

Convenience: the three web-SPA localStorage entries (quasar.auth.token / quasar.auth.expires_at / quasar.auth.user) ready to inject.

object

key

additional properties

string

Example

{
  "token_type": "Bearer",
  "user": {
    "role": "user"
  }
}

400

Malformed or invalid request.

application/json

object

error

required

object

code

required

E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, host_not_ready, restart_required, stale_revision, unsupported_source, approval_superseded, approval_expired, attempt_conflict, cancel_too_late, retry_exhausted, home_conflict, placement_ineligible, inherited_placement, recovery_uncertain, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.

string

message

required

string

live_sessions

Present on restart_required.

integer

session_id

Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Also omitted when the holder is the caller’s parked session or released runtime (amendment 39). Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.

string format: uuid

derived_tiles

Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.

Array<object>

object

required

string format: uuid

name

required

string

reason

Amendment 40 (#602), ADDITIVE: a machine-readable cause under code. On 503 no_host_available, home_host_unavailable: the launch is pinned to the host that holds the caller’s home for this app (Amendment 53: or it is pinned to the host of the caller’s Steam home for a sharing launch) and that host is offline or no longer enrolled. Only an admin clears it, so a client does not spend its automatic retry on it. Names no host. Amendment 53 (#1001), on 409 home_in_use: steam_library_open_in_desktop (the holder mounts the Steam library as a shared home) or steam_game_running (the refused launch shares the library and a Steam session holds it); absent when the holder is already stopping. Open string: a client treats an unknown value as absent.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "live_sessions": 1,
    "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "derived_tiles": [
      {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "name": "example"
      }
    ],
    "reason": "example"
  }
}

401

Missing/invalid/expired/revoked token.

application/json

object

error

required

object

code

required

string

message

required

string

live_sessions

Present on restart_required.

integer

session_id

string format: uuid

derived_tiles

Array<object>

object

required

string format: uuid

name

required

string

reason

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "live_sessions": 1,
    "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "derived_tiles": [
      {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "name": "example"
      }
    ],
    "reason": "example"
  }
}

Mint a throwaway, auto-reaped ephemeral identity + token for automated UI validation (dev-gated;

Parameters

Header Parameters

Request Body

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

Example^generated

Example^generated