Iniciar sesión con UTILIA con el SDK Python

El SDK Python de UTILIA OS (utilia-sdk) resuelve el flujo OAuth por ti: genera el par PKCE y el state, construye la URL de autorización, canjea el código, guarda los tokens y los renueva antes de que caduquen. Tiene un cliente asíncrono (UtiliaSDK) y otro síncrono (UtiliaSDKSync) con los mismos métodos.

Está pensado para scripts, herramientas de línea de órdenes y aplicaciones de escritorio, en las que una sola persona inicia sesión. Para una aplicación web con muchas personas a la vez, como Flask o Django, usa Authlib, como en Iniciar sesión con UTILIA en Flask.

Antes de empezar

• Python 3.9 o superior.
• Activa OAuth en tu aplicación externa, como explica Activar OAuth en tu aplicación, y registra como dirección de vuelta, por ejemplo, http://localhost:8000/callback.
• Instala el SDK:

pip install utilia-sdk

Flujo asíncrono

1. Crea el SDK con OAuth

   Python

   import os
    
   from utilia_sdk import FileTokenStorage, UtiliaSDK
    
   sdk = UtiliaSDK(
       base_url="https://os.utilia.ai/api",
       oauth={
           "client_id": os.environ["UTILIA_CLIENT_ID"],
           "client_secret": os.environ.get("UTILIA_CLIENT_SECRET"),  # solo con servidor propio
           "redirect_uri": "http://localhost:8000/callback",
           "scopes": ["openid", "profile", "email"],
           "token_storage": FileTokenStorage(".utilia-tokens.json"),
       },
   )

   FileTokenStorage guarda los tokens y el estado pendiente en un archivo, así que sobreviven entre ejecuciones. Si la aplicación se ejecuta en el equipo de la persona, no pongas client_secret: no se puede guardar en secreto, y PKCE la protege.

2. Lleva a la persona a autorizar

   Python

   auth_url = await sdk.oauth.get_authorization_url()
   print(f"Abre esta URL en tu navegador: {auth_url}")

   Admite opciones como scopes, resource, prompt y state.

3. Canjea el código

   Cuando UTILIA OS devuelve a la persona a tu dirección de vuelta, recoge code y state:

   Python

   tokens = await sdk.oauth.handle_callback(code, callback_state=state)
   print(tokens.scope)  # lo que la persona concedió de verdad

   Con callback_state, el SDK comprueba que la respuesta es la de tu petición.

4. Obtén los datos de la persona

   Python

   user = await sdk.oauth.get_user_info()
    
   print(user.sub)    # identificador estable
   print(user.name)
   print(user.email)

   En el cliente asíncrono, get_user_info() es una corrutina: sin await devolvería la corrutina y no los datos.

Al arrancar de nuevo, comprueba si ya hay sesión:

if await sdk.oauth.is_authenticated():
    user = await sdk.oauth.get_user_info()
    print(f"Hola, {user.name}")
else:
    print(f"Abre esta URL: {await sdk.oauth.get_authorization_url()}")

Flujo síncrono

import os
 
from utilia_sdk import FileTokenStorage, UtiliaSDKSync
 
sdk = UtiliaSDKSync(
    base_url="https://os.utilia.ai/api",
    oauth={
        "client_id": os.environ["UTILIA_CLIENT_ID"],
        "redirect_uri": "http://localhost:8000/callback",
        "scopes": ["openid", "profile", "email"],
        "token_storage": FileTokenStorage(".utilia-tokens.json"),
    },
)
 
print(f"Abre esta URL en tu navegador: {sdk.oauth.get_authorization_url()}")
 
code = input("Pega el valor de code de la dirección de vuelta: ")
state = input("Pega el valor de state: ")
sdk.oauth.handle_callback(code, callback_state=state)
 
user = sdk.oauth.get_user_info()
print(f"Hola, {user.name} ({user.email})")

Renovación y errores

El SDK renueva el access token automáticamente antes de que caduque y guarda el refresh token nuevo de cada renovación, como exige la rotación del refresh token. Si la renovación ya no es posible (la cadena caducó o se revocó, o la persona perdió el acceso), la llamada lanza una excepción: trátala volviendo a pedir la autorización.

try:
    user = await sdk.oauth.get_user_info()
except Exception:
    await sdk.oauth.revoke_token()  # limpia lo guardado
    print(f"La sesión ha caducado. Autoriza de nuevo: {await sdk.oauth.get_authorization_url()}")

Cerrar sesión

await sdk.oauth.logout()   # en el cliente síncrono: sdk.oauth.logout()

Revoca el access token en UTILIA OS, lo que anula también el refresh token de esa emisión, y borra los tokens guardados.

Qué puedes hacer con el token

El token de este flujo sirve para identificar a la persona y para llamar a los servidores MCP de UTILIA OS en su nombre (pide su resource y sus scopes al autorizar). Los servicios REST del SDK, como sdk.tickets o sdk.users, usan la API externa y se configuran con la clave de API de tu aplicación (api_key), no con OAuth.

La referencia completa de la configuración OAuth del SDK está en SDK Python: OAuth.