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 = CUA_RELAY_URL, else https://relay.cua.ai) as the signed-in account, shown as name (default: the host 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 = CUA_RELAY_URL, else
https://relay.cua.ai) as the signed-in account, shown as name
(default: the host 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.
A device that already enrolled (it has a device key) then
re-registers with the relay (CUA_RELAY_URL, else relay.cua.ai), 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