nebius.aio.token.federation_account

module documentation
(source)

High-level federation bearer that provides cached, renewable tokens.

This module exposes FederationBearer, a convenience bearer that composes the interactive federation authorization implementation (nebius.aio.token.federation_bearer.Bearer) with the asynchronous file-backed renewable cache (nebius.aio.token.file_cache.async_renewable_bearer.AsynchronousRenewableFileCacheBearer).

Behavior and authorization flow

When a token is requested via nebius.aio.token.token.Receiver.fetch the following sequence may occur:

  1. The cache is consulted for a fresh token. If a cached token is valid it is returned immediately.

  2. If renewal is required the underlying interactive flow is invoked. This flow is implemented by nebius.aio.token.federation_bearer.Receiver and will typically:

    • construct an authorization URL and attempt to open the user's browser (unless no_browser_open is set), or return the URL so callers can display it.
    • block while waiting for the user to complete the authorization in the browser (for example by granting access). This means the fetch may hang until the user completes the flow.
    • receive an access token and expiration and return it to the caller.

Where the URL is shown

  • The interactive helper logs the authorization URL so it appears in the application's logs.
  • If a writer stream is provided the helper will also write the URL and short instructions to that stream (e.g. stdout), which is useful for headless environments.

Usage

The FederationBearer wraps the interactive bearer with a file-backed renewable cache and exposes the usual receiver API:

fb = FederationBearer(profile_name, client_id, endpoint, federation_id)
token = await fb.receiver().fetch()

Note that because interactive authorization may block, callers should use timeouts or call fetch from a background task when appropriate.

Class FederationBearer Bearer composing interactive federation auth with a renewable cache.