Simulators
Session tasks
Clerk can hold a signed-in session as pending until the user finishes a required step. The simulator does this for the step an instance that requires an organization asks for: choosing one. The session runs on the browser companion, so boot the simulator as that page does:
PORT=$(python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1])')
export RYSTIC_URL=$(rystic run clerk-twin --runner native -d --port "$PORT" --env CLERK_TWIN_SITE_ORIGIN=http://localhost:3000 --env CLERK_TWIN_ISSUER="http://127.0.0.1:$PORT" --json | jq -r .data.url)
curl -s -o /dev/null -w '%{http_code}\n' "$RYSTIC_URL/_twin/config"
# -> 200
Require an organization
Until an instance turns session tasks on, no session is pending and its token includes no sts claim, as for a Clerk instance that has not opted in:
curl -s -X POST "$RYSTIC_URL/_twin/sign-in" -H 'Content-Type: application/json' -d '{"email":"noor@example.test"}' | jq -r '.token | split(".")[1] | gsub("-"; "+") | gsub("_"; "/") | . + ("=" * ((4 - length % 4) % 4)) | @base64d | fromjson | .sts'
# -> null
The instance’s settings are one seeded record, state_browser_instance, keyed instance. With organization_required set, a session with no active organization is pending on the choose-organization task, and its token includes sts: "pending":
curl -s -o /dev/null -w '%{http_code}\n' -X POST "$RYSTIC_URL/_rystic/seed" -H 'Content-Type: application/json' -d '{"state_browser_instance":{"instance":{"id":"instance","organization_required":true}}}'
# -> 204
SIGNIN=$(curl -s -X POST "$RYSTIC_URL/_twin/sign-in" -H 'Content-Type: application/json' -d '{"email":"lena@example.test"}')
echo "$SIGNIN" | jq -c '{status: .session.status, task: .session.current_task.key}'
# -> {"status":"pending","task":"choose-organization"}
echo "$SIGNIN" | jq -r '.token | split(".")[1] | gsub("-"; "+") | gsub("_"; "/") | . + ("=" * ((4 - length % 4) % 4)) | @base64d | fromjson | .sts'
# -> pending
Creating or choosing an organization finishes the task. The session becomes active and its token includes sts: "active":
TOKEN=$(echo "$SIGNIN" | jq -r .token)
ORG=$(curl -s -X POST "$RYSTIC_URL/_twin/organizations" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"name":"Lena Co"}')
echo "$ORG" | jq -c '{status: .session.status, task: .session.current_task}'
# -> {"status":"active","task":null}
echo "$ORG" | jq -r '.token | split(".")[1] | gsub("-"; "+") | gsub("_"; "/") | . + ("=" * ((4 - length % 4) % 4)) | @base64d | fromjson | .sts'
# -> active
What session tasks do not do
Differs from Clerk: choose-organization is the only task.