Connecting

A connection binds the console to one AcasoOS instance and one tenant. This page covers the full lifecycle: adding, switching, and re-authenticating.

Add a connection

Open /connect (the console redirects here automatically when no active connection exists). The form asks for three values:

On submit, the console issues:

curl -X POST "https://your-acaso.example.com/v1/auth/session" \
  -H "Authorization: Bearer <long-lived-key>"

A 2xx response returns the session token, the resolved user, and the tenant. The console stores {url, name, session_token, expires_at, user_id, user_display_name, tenant_id, tenant_slug} in sessionStorage and forgets the long-lived key.

A non-2xx response leaves the form intact, surfaces an inline error, and saves nothing. The key input is cleared so it does not linger in the DOM.

Switch connections

The connection switcher sits in the top-left chrome. Clicking another connection re-mounts every server-state query against that connection's URL with its session token. No requests fire against the previous connection during or after the switch.

Note: Each tab keeps its own sessionStorage, so the active connection is per-tab. Two tabs against the same instance hold independent sessions; both stay valid until the parent key is revoked.

Re-authenticate

The console detects an expired session in two ways:

• Any API response returns 401.
• The session's expires_at is within 5 minutes.

Either trigger redirects you to /connect with the URL and Name fields pre-filled and a banner explaining the session expired. Paste your long-lived key again; on a successful exchange the console returns you to the route you were on before the expiry.

Remove a connection

Open the switcher, hover the connection, and click Remove. The local record is deleted from sessionStorage. The session token on the server stays valid until it expires (or until its parent key is revoked); removing the local copy simply forgets it.

Recover from a wrong URL

If you typed an unreachable URL or the wrong scheme (for example http:// against a TLS-only deployment), the exchange call fails at the transport layer. The console reports the underlying error and does not save the connection. Correct the URL and try again.