Repository navigation
Credential Storage
The CredentialStorage abstraction, its four concrete backends, and how create_storage() picks one.
Every backend in src/eero/api/auth_storage.py implements the same abstract base class:
class CredentialStorage(ABC):
async def load(self) -> AuthCredentials: ...
async def save(self, credentials: AuthCredentials) -> bool: ...
async def clear(self) -> None: ...AuthCredentials is a plain @dataclass with exactly one field โ session_id โ plus helpers to_dict(), from_dict(), and clear_all(). Every backend round-trips this object; none of them know about networks, profiles, or anything besides the session token. There is no expiry field and no refresh token: the server decides whether a token is still valid, and refreshing reuses the same token (see Authentication).
to_dict() produces the persisted record shape, which is the same for every backend:
{
"session_id": "โฆ",
"schema_version": 2
}schema_version is eero.const.CREDENTIAL_SCHEMA_VERSION. A stored record without that key is a legacy record from an earlier release โ it may use the pre-v3.0.0 user_token key instead of session_id, and may carry the extra fields 7.x wrote alongside the token (named in Migration). Each backend's load() migrates such a record in place: it keeps the token (reading session_id, falling back to user_token), drops every other field, and re-saves the record in the current shape. The migration runs once per backend, is idempotent (a record that already carries schema_version is never rewritten), and logs no values โ a DEBUG line that a migration happened, then a read-back check that logs DEBUG on match or WARNING on mismatch (the in-memory credentials are returned either way).
save() never raises and returns whether the backend now holds the saved token, judged by reading it back rather than by the write not raising (a write call that returns normally proves nothing: a no-op keyring accepts everything). Callers that ignore the return value keep working. A third-party backend written against the earlier -> None contract may still return None; AuthAPI treats that as "unknown, assume persisted" rather than as a failure. MemoryStorage returns True because it holds the record for the life of the process, not because it is durable.
AuthAPI owns exactly one CredentialStorage instance (built by create_storage() in its __init__) and calls load() on __aenter__, save() after verify() and set_session_token() (never after login(), whose pending token stays in memory until verification succeeds), and clear() from logout(), clear_session_token(), clear_auth_data() and a refresh that reports the session as terminated. AuthAPI records the outcome of each save and exposes it as the read-only property credentials_persisted (also on EeroAPI and EeroClient): False only when the last saved session was read back and no backend retained it, True otherwise (including after a load or a clear, and when login() installs a pending token, which is never saved). login() and verify() keep returning only the API outcome, so check this property when losing the session on exit matters.
There are four concrete implementations: KeyringStorage, FileStorage, MemoryStorage, ChainedStorage.
KeyringStorage and FileStorage do blocking work (keyring calls, open, fsync, os.replace), so they run each load(), save() and clear() on a worker thread with asyncio.to_thread instead of on the event loop. A slow keyring or disk stalls only that call, not the rest of your application (which matters for a long-running async host such as a web service during login or logout).
-
One thread hop per operation. The whole synchronous unit runs in the thread: for
save()that includes the write and its read-back; forload()it includes a legacy-record migration and the migration's read-back. Behaviour, return values and log lines are unchanged. -
Serialised per instance. Each instance holds an
asyncio.Lockaround every thread hop, so asave()and aclear()on the same backend cannot interleave: whichever you awaited first runs first, and the other waits. Separate instances (for example twoFileStorageobjects on the same path) are not coordinated with each other. -
Cancellation does not stop a running thread. If the task awaiting an operation is cancelled while its thread is already running, the thread runs to completion. A
save()still finishes its atomicos.replace(), so afterwards the file holds either the previous record or the new one, never a partial one; the cancelled caller simply never sees the result. The lock stays held until the thread finishes, so the next operation on that instance waits instead of racing it. An operation that is only waiting for the lock is cancelled outright and does no work. -
The lock is per event loop. It is created on first use rather than in the constructor, so building a backend never binds it to a loop, and a backend reused from a later
asyncio.run()gets a fresh lock for that loop. -
MemoryStorageandChainedStorageuse no threads of their own: the memory backend does no I/O, and the chain just awaits its backends (so it inherits their serialisation).
def create_storage(
use_keyring: bool = True,
cookie_file: Optional[str] = None,
) -> CredentialStorage:This is the only place backend selection happens โ driven purely by the use_keyring / cookie_file values you pass into EeroClient(...) (which flow through EeroAPI โ AuthAPI unchanged).
use_keyring |
cookie_file |
Backend returned |
|---|---|---|
True |
set | ChainedStorage(primary=KeyringStorage(), fallback=FileStorage(cookie_file)) |
True |
None |
KeyringStorage() |
False |
set | FileStorage(cookie_file) |
False |
None |
MemoryStorage() |
In prose: keyring is tried whenever use_keyring=True; a file path is only ever consulted as a fallback alongside keyring, or as the sole backend when you explicitly disable keyring; and if you disable keyring without giving a file path, there is nothing left to fall back to, so credentials live in memory only for the life of the process.
class KeyringStorage(CredentialStorage):
SERVICE_NAME = "eero-api"
ACCOUNT_NAME = "auth-tokens"Delegates to the third-party keyring package, which resolves a platform backend at import time:
| OS | Backend |
|---|---|
| ๐ macOS | Keychain |
| ๐ง Linux | Secret Service (GNOME Keyring, KWallet) |
| ๐ช Windows | Windows Credential Locker |
load() calls keyring.get_password(SERVICE_NAME, ACCOUNT_NAME), JSON-decodes the result into an AuthCredentials, and โ if the stored record was a legacy one (no schema_version key) โ re-saves it in the current shape before returning it. save() JSON-encodes credentials.to_dict(), calls keyring.set_password(...), then reads the entry back with keyring.get_password(...) and returns True only if the stored session_id matches. clear() calls keyring.delete_password(...), swallowing keyring.errors.PasswordDeleteError silently (nothing to delete is not an error) and logging any other exception at DEBUG; clear() never raises. Every keyring call happens on a worker thread (see Threads, locking and cancellation).
Note:
load()andsave()wrap the underlyingkeyringcalls in a bareexcept Exception, so a locked keyring, a missing Secret Service daemon on headless Linux, or any other backend failure is non-fatal:load()returns an emptyAuthCredentials()andsave()returnsFalse, never raising. A backend that reports success without persisting anything (e.g.keyring.backends.null.Keyring) is caught the same way, by the read-back.
โ ๏ธ Warning: With the defaultEeroClient()(use_keyring=True, nocookie_file) the keyring is the only backend. If it retains nothing,login()/verify()still succeed and the session works for this process, but it is not persisted anywhere and is lost on exit.save()logs a fixedWARNING("Keyring did not retain the session; credentials are not persisted and will be lost when this process exits", never the token), andcredentials_persistedisFalse. To fix it, give the client acookie_fileso there is a fallback, or useuse_keyring=False, cookie_file=.... Whencreate_storage()layers a file behind the keyring it buildsKeyringStorage(warn_on_unpersisted=False): the keyring failing to retain a write is routine there and handled by the fallback, so that warning is suppressed (the keyring still returnsFalseand logs the cause atDEBUG).
class FileStorage(CredentialStorage):
def __init__(self, file_path: str) -> None- The path is resolved eagerly in
__init__viaos.path.abspath(os.path.expanduser(file_path))โ~is expanded and the result is made absolute. There is no default path; you must always supply one. -
file_pathis a read-only@propertyreturning the resolved path. -
load()returns an emptyAuthCredentials()if the file doesn't exist or fails to parse as JSON (FileNotFoundError,json.JSONDecodeErrorcaught explicitly; any other exception is caught too and logged atWARNING). A legacy record found on disk is migrated and re-saved, same asKeyringStorage. -
save()creates the parent directory (os.makedirs(..., exist_ok=True)), refuses to write iffile_pathis a symlink, writesjson.dumps(credentials.to_dict())to a freshtempfile.mkstemp()file in the same directory (created0600),fsyncs it, re-asserts0600withos.chmod, then atomically swaps it into place withos.replace(). A crash mid-write leaves the previous file or nothing โ never a partial record. The file is then read back, andsave()returnsTrueonly if the stored token matches (a mismatch logs a fixedWARNING). Any failure is logged atERRORand swallowed, returningFalse;save()never raises. The exact keys written are:
{
"session_id": "โฆ",
"schema_version": 2
}Note: If your own tooling reads this file, read
session_idonly. The extra fields 7.x wrote are no longer written, and any copy of them still sitting in an old file is dropped the first time the SDK loads it โ see Migration.
- Every step above, including the read-back, runs on one worker thread under the instance lock (see Threads, locking and cancellation). Cancelling a
save()mid-flight cannot leave a half-written file: the temporary file is swapped in atomically or removed, so the destination holds the old record or the new one, still0600. -
clear()removes the file withos.remove()if it exists (a missing file is a silent no-op); a removal error is logged atWARNINGand swallowed (never raises).
class ChainedStorage(CredentialStorage):
def __init__(self, primary: CredentialStorage, fallback: CredentialStorage) -> NoneOnly ever constructed by create_storage() as ChainedStorage(primary=KeyringStorage(), fallback=FileStorage(cookie_file)) โ but nothing stops you from composing it yourself with any two CredentialStorage instances. ChainedStorage performs no legacy-record migration of its own; each underlying backend migrates on its own load().
| Operation | Order of operations | On partial failure |
|---|---|---|
load() |
Try primary.load() first. If it returns credentials with a session_id, return them immediately. Otherwise try fallback.load(). |
If the fallback holds a session_id, it is promoted with primary.save(credentials); the primary is then re-loaded and, if the read-back matches, fallback.clear() deletes the fallback copy so only one backend holds the live record. If the read-back does not match, the fallback copy is kept (DEBUG log). |
save() |
Try primary.save(). If it does not raise, read the primary back with primary.load() and compare session_id to what was just saved. |
If primary.save() raises, or the read-back doesn't match what was saved, fallback.save() is attempted (both cases are logged at DEBUG) and the fallback is read back too. If both the primary path and fallback.save() fail, the fallback's exception is logged at ERROR and swallowed โ save() never raises to the caller. Returns True if either backend was read back holding the token. A verified primary write does not write the fallback, and instead retires the fallback record (best effort; a failing clear is logged at DEBUG and ignored), so a superseded token cannot be resurrected by load()'s promotion if the primary is wiped later. The fallback is read back first and cleared only if it still holds a record this instance superseded: the token it last loaded from, promoted out of, or wrote to the fallback, or the token just saved. A different session found there (another process sharing the cookie file, with no working keyring) is left in place and logged at DEBUG. |
clear() |
Attempts primary.clear() and fallback.clear() independently; one raising never skips the other. |
A backend that raises is logged at WARNING (fixed text) and ignored. clear() raises only if both backends raised, and then re-raises the first error after both were attempted. logout(), clear_session_token() and clear_auth_data() therefore never raise because of a single failing backend; the in-memory token is cleared first in any case. |
โน๏ธ Note:
save()verifies the primary write with a read-back before skipping the file fallback.KeyringStorage.save()catches its own exceptions internally and returns normally instead of raising (see above), and some keyring backends (e.g.keyring.backends.null.Keyring) report success without persisting anything at all โ no exception, ever. Relying onprimary.save()raising would miss both cases, soChainedStorage.save()instead mirrors the read-back-then-act patternload()'s own promotion logic already uses: after a primary write that didn't raise, it re-load()s the primary and comparessession_idagainst what it just wrote. Only a matching read-back skips the fallback; any mismatch โ raised exception or silent no-op alike โ falls through tofallback.save(), soChainedStorage(use_keyring=Truewith acookie_fileset) is a viable choice for headless/CI/container persistence.use_keyring=False, cookie_file=...(plainFileStorage) remains valid too, and is simpler if you have no use for the keyring at all.
class MemoryStorage(CredentialStorage):
def __init__(self) -> NoneHolds one AuthCredentials instance as a plain attribute. load() returns a copy and save() stores a copy, so mutating the live credentials object in place cannot change the stored record without going through save()/clear(); clear() resets the attribute. No I/O, no serialization, nothing ever touches disk.
โ ๏ธ Warning: This is the silent-data-loss backend.EeroClient(use_keyring=False)with nocookie_fileresolves here automatically (see the selection table above) โ there is no error, warning, or log line telling you this happened. Every session, once the process exits, is gone. Only use this deliberately (tests, short-lived ephemeral processes, secrets injected fresh every run viaset_session_token()).
| Deployment scenario | Recommended construction | Why |
|---|---|---|
| ๐ฅ๏ธ Desktop (macOS/Windows/Linux w/ desktop env) |
EeroClient() (defaults) |
KeyringStorage alone โ OS-encrypted, no file to protect |
| ๐ง Headless Linux (no Secret Service daemon) | EeroClient(use_keyring=False, cookie_file="/path/to/creds.json") |
A keyring-only setup retains nothing here (save() warns and credentials_persisted is False); with a cookie_file, ChainedStorage's read-back catches that and falls through to the file (see note above), but there's no keyring to gain anything from here anyway โ skip it entirely and go straight to FileStorage
|
| ๐ณ Docker container | EeroClient(use_keyring=False, cookie_file="/data/eero-cookies.json") |
No keyring daemon available inside most containers; skip straight to FileStorage and mount /data as a volume for persistence across restarts |
| ๐ค CI pipeline |
EeroClient(use_keyring=False, cookie_file=<workspace path>) + set_session_token() from a CI secret |
No interactive OTP possible; seed the token directly each run (see Authentication) |
| โ๏ธ Serverless / ephemeral (Lambda-style, no writable disk) | EeroClient(use_keyring=False) |
Falls through to MemoryStorage deliberately โ nothing to persist between invocations anyway; re-seed via set_session_token() on every cold start |
The source does not expose an injection point on EeroClient, EeroAPI, or AuthAPI for supplying your own CredentialStorage implementation โ AuthAPI.__init__ always calls create_storage(use_keyring, cookie_file) internally, and that function only ever returns one of the four built-in classes. If you need different storage behavior (e.g. a secrets-manager-backed store), your options are:
- Subclass
CredentialStorageyourself and manage it entirely outside this SDK, usingset_session_token()/clear_session_token()onEeroClientto move data in and out ofAuthAPIat the times that matter to you. - Use
cookie_filepointed at a path your own tooling manages (e.g. a file synced from a secrets manager before the process starts).
There is no monkey-patch-free extension point beyond that โ don't assume one exists.
| Goal | Call |
|---|---|
| Rotate to a new externally-issued token | await client.set_session_token(new_token) |
| Drop the active session locally, no server round-trip | await client.clear_session_token() |
| Log out and tell the server too | await client.logout() |
Same as clear_session_token() plus resets the login-in-progress flag, the preferred network and the in-memory cache |
await client.clear_auth_data() (since v8.4.0) |
Every credential-dropping call above (clear_session_token, logout, clear_auth_data) deletes the stored record from every backend โ there is no "re-save an empty record" variant. The operations exposed on EeroClient also invalidate its in-memory response cache as a side effect (set_session_token, clear_session_token and clear_auth_data always; logout when it returns True, i.e. whenever credentials were actually present), so a rotated or cleared session never serves stale cached data.
- Home โ Overview and quick start
- Configuration โ Storage-selection summary table and constructor options
- Authentication โ Login/verify flow, session transport, and what gets persisted
- Migration โ What changed in the credential record in v8.0.0
- Logging and Security โ Sensitive-field redaction in logs
- Troubleshooting โ Common issues & fixes
eero-api โ unofficial async Python client for the Eero cloud API. Not affiliated with or endorsed by Eero.
This wiki is generated from wiki/ in the main repository โ edit there, not here. ยท MIT License