Authentication

Access your saved SE3 Labs login and account information from Python.

Sign in with se3labs auth login before using the SDK. The Evaluation Client uses this login automatically for serve_policy() and get_status(); you normally do not need to obtain or pass tokens yourself.

from se3labs.sdk.auth import Client

client = Client()
identity = client.user()
print(identity["name"], identity["email"])

Saved login

Run se3labs auth login and approve the displayed code in the browser. For a remote terminal, se3labs auth login --no-browser prints the URL; open it on any device to approve that terminal. See Installation for the login walkthrough and Command Line for command options.

After approval and a successful account check, the login is saved in ~/.se3labs/production.json by default, with file permissions restricted to the owner. The CLI and Python SDK share this file for the same operating system user. SDK processes coordinate credential reads and token refreshes with a file lock.

se3labs auth whoami checks the saved account and lists its organizations. se3labs auth logout removes the local login and requests revocation of its refresh token. The local file is removed even if the revocation request fails.

Client

Client(env: str | None = None)

Use the saved login to obtain an access token or read your account.

Construct with Client() for normal use. Construction selects the service configuration; credentials are loaded when you call access_token() or user(). Creating a client does not sign you in or verify that a saved login exists.

Parameter: env optionally selects an SDK service configuration. If omitted, the SDK uses SE3_ENV when set, otherwise production. An unknown configuration name raises KeyError.

Attributes

env: Environment

Resolved service configuration. env.api is the API origin and env.credentials is the saved-login path.

Methods

access_token() -> str

Return the bearer access token as a string, without the "Bearer " prefix.

Reads the saved login on every call. A token with at least 60 seconds remaining is returned without a network request. With less time remaining, the SDK refreshes it and saves the new access token, rotated refresh token, and expiry under a file lock.

Use this method when an integration explicitly needs a token. Call it again when a new token is needed; a previously returned string is not updated when the saved login changes. SDK methods such as serve_policy() and get_status() obtain their own tokens.

Raises: AuthError if no login is saved, the login service rejects a refresh, or the login service cannot be reached or returns an unreadable response. A rejected refresh requires a new login; a connection failure can be retried after connectivity is restored.

user() -> dict

Fetch the current account and its organization memberships.

Calls access_token() first, then fetches the identity from the SE3 API. Every call makes a request; the identity is not cached.

Returns: a dictionary with these fields:

Field	Value
user_id	str: your SE3 account ID.
name	str: your display name.
email	str: your account email address.
organizations	list[dict]: your organization memberships, oldest first.

Each organization has org_id and org_name strings, plus role, either "admin" or "member" for your membership in that organization.

Raises: AuthError for a missing or unusable saved login, an API refusal, or a connection failure. API refusals during this lookup produce an empty AuthError.code.

AuthError

AuthError(message: str, code: str = '')

A login, token refresh, or account lookup failed.

Catch AuthError around authentication operations. str(error) gives the message to display; its wording is not a stable error identifier.

Failure	What to do
No saved login	Run se3labs auth login as the operating system user that runs the SDK.
Refresh rejected or saved login no longer accepted	Run se3labs auth login again.
Browser approval timed out	Start login again and approve the new code.
API or login service cannot be reached	Restore connectivity, then retry the operation.

code is available for some service errors, such as a rejected token refresh. It can also be empty for a server refusal: Client.user() translates API errors without preserving their codes. An empty code alone does not identify the cause.

Attributes

code: str

Optional service error identifier, such as NotAuthorizedException or forbidden. Empty when no code is attached.