Auth
Sign-in and the credential store the SDK, the CLI and the daemon share.
Sign-in and the credential store the SDK, the CLI and the daemon share.
cua.auth() signs in and reads the shared session. Cloud calls use it when no Fleet token or client credentials are configured.
Python programs usually use the high-level API instead: cua_sandbox.configure().
Auth#Sign-in and the shared session.
Returned by Cua.auth.
| Method | Description |
|---|---|
access_token | A valid access token (refreshed when it expires within a minute, or when force). |
begin_login | Starts a sign-in. |
devices | This device on relay_url (None = the relay cua uses: CUA_RELAY_URL, else this machine's host setup, else https://relay.cua.ai) as the signed-in account, shown as name (default: this computer's name). |
logout | Revokes (best effort) and removes the session. |
status | The stored session (no network). |
Auth.access_token#A valid access token (refreshed when it expires within a minute, or
when force). Unauthenticated when not signed in.
async def access_token(self, force: bool) -> str| Parameter | Type | Default |
|---|---|---|
force | bool | required |
Returns String · Async · Raises CuaError (Unauthenticated)
Auth.begin_login#Starts a sign-in. flow: auto (default: browser, else device
code), browser or device.
async def begin_login(self, flow: Optional[str]) -> LoginAttempt| Parameter | Type | Default |
|---|---|---|
flow | Option<String> | required |
Returns LoginAttempt · Async · Raises CuaError
Auth.devices#This device on relay_url (None = the relay cua uses:
CUA_RELAY_URL, else this machine's host setup, else
https://relay.cua.ai) as the signed-in account, shown as name
(default: this computer's name).
def devices(self, relay_url: Optional[str], name: Optional[str]) -> Devices| Parameter | Type | Default |
|---|---|---|
relay_url | Option<String> | required |
name | Option<String> | required |
Returns Devices · Raises CuaError
Auth.logout#Revokes (best effort) and removes the session. Returns whether one existed.
async def logout(self) -> boolReturns bool · Async · Raises CuaError
Auth.status#The stored session (no network).
def status(self) -> AuthStatusReturns AuthStatus · Raises CuaError
LoginAttempt#A started sign-in. Show url (and user_code), then await wait().
Returned by Auth.begin_login.
| Method | Description |
|---|---|
wait | Waits for the user, stores the session and returns who signed in. |
| Accessor | Returns | Description |
|---|---|---|
method() | LoginMethod | Browser or device. |
note() | Option<String> | Why a device code is used although browser sign-in was asked for. |
url() | String | The URL to open. |
user_code() | Option<String> | Device flow: the code to enter. |
LoginAttempt.wait#Waits for the user, stores the session and returns who signed in. Only the first call waits; later calls fail.
This device then registers with the relay (the one cua uses:
CUA_RELAY_URL, else this machine's host setup, else relay.cua.ai),
creating its device key on first use, so the fresh sign-in enrolls
or re-verifies it without an approval. That step is best effort and
never fails the sign-in.
async def wait(self) -> AuthIdentityReturns AuthIdentity · Async · Raises CuaError
AuthIdentity record#Who is signed in (from token claims; display only).
Returned by LoginAttempt.wait.
| Field | Type | Default | Description |
|---|---|---|---|
username | Option<String> | preferred_username. | |
email | Option<String> | email. | |
name | Option<String> | name. | |
subject | Option<String> | sub. | |
display | Option<String> | One display string (email, else username, else subject). |
AuthStatus record#The stored session, read without network access.
Returned by Auth.status.
| Field | Type | Default | Description |
|---|---|---|---|
logged_in / loggedIn | bool | A session is stored. | |
identity | Option<AuthIdentity> | Who. | |
expires_at / expiresAt | Option<String> | RFC 3339 expiry of the current access token (it refreshes itself). | |
store | String | Where credentials live. |
LoginMethod enum#How a sign-in proceeds.
LoginMethod.BROWSER
LoginMethod.DEVICE| Variant | Description |
|---|---|
Browser | Open url in a browser on this machine; it redirects back here. |
Device | Open url on any device and enter user_code. |
may_have_fleet_session#Whether a cua auth login session may be stored, decided without
reading the OS credential vault (the non-secret session marker, or the
file store's file). Implicit callers (the default sandbox listing) check
this before reading the session; an explicit read of a session stored
before markers existed writes the marker.
def may_have_fleet_session() -> boolReturns bool