Skip to content

Authentication

pyfamilysafety does not embed a browser login flow. You sign in through Microsoft in a browser, then pass the resulting redirect URL (or a saved refresh token) to Authenticator.create.

OAuth login (first time)

  1. Open this URL in a browser (while signed in to the Microsoft account that manages your family):

Microsoft Family Safety OAuth login

  1. Complete Microsoft sign-in. You are redirected to a blank page on login.live.com/oauth20_desktop.srf.

  2. Copy the entire URL from the browser address bar. It contains a code= query parameter.

  3. Pass that URL to the authenticator:

import asyncio
from pyfamilysafety import Authenticator

async def main():
    redirect_url = "https://login.live.com/oauth20_desktop.srf?code=..."
    auth = await Authenticator.create(token=redirect_url)
    print("Logged in as", auth.user_id)
    # Save auth.refresh_token for later sessions

asyncio.run(main())

Refresh token sessions

For long-running apps, store auth.refresh_token securely and reuse it:

auth = await Authenticator.create(
    token=stored_refresh_token,
    use_refresh_token=True,
)

Automatic token refresh

Access tokens expire after a short period. FamilySafetyAPI refreshes the token automatically before each request when auth.access_token_expired is true. You do not need to call perform_refresh() yourself during normal use.

Session sharing

Pass an existing aiohttp.ClientSession if you manage HTTP connections yourself:

import aiohttp
from pyfamilysafety import Authenticator

async with aiohttp.ClientSession() as session:
    auth = await Authenticator.create(token=redirect_url, client_session=session)

Privacy and scope

The OAuth scope is restricted to the Family Safety service (service::familymobile.microsoft.com::MBI_SSL). Tokens grant access to Family Safety APIs only — not OneDrive, Outlook, or other Microsoft services. See the FAQ for more detail.

Next: Quick start