Autenticación

El CLI tecsas3-cli soporta dos esquemas de autenticación contra el backend Django del Ecosistema Salud TecsaS3: el DRF Token legacy y JWT (SimpleJWT). Ambos se almacenan localmente en el keyring del sistema operativo o, cuando este no está disponible, en un archivo con permisos 0600 que sólo el usuario actual puede leer y escribir. Esta página documenta los sub-comandos de tecsas3 auth, los mecanismos de almacenamiento de credenciales y la auto-detección del tipo de token en tiempo de ejecución. Para la configuración de tenant y perfiles, consulta configuration.

Esquemas de autenticación

DRF Token
JWT

Token opaco de 40 caracteres generado por rest_framework.authtoken y expuesto en POST /api/autenticar/. Es el esquema por defecto del CLI y se envía como Authorization: Token <KEY>. Se utiliza en flujos legacy y tokens de larga duración asociados a un usuario.

# Login con DRF Token (esquema por defecto).
tecsas3 auth login --user ana@eps.example --password "$PWD" --scheme token

# O equivalente con clave API pre-emitida.
tecsas3 auth login --api-key 9944b09199c62bcf9418ad846dd0... --scheme token

Par de tokens firmados con HS256 emitidos por djangorestframework-simplejwt desde POST /api/token/. El CLI guarda el access (corta duración) y, si está presente, el refresh. El header enviado es Authorization: Bearer <JWT>.

# Login con JWT.
tecsas3 auth login --user ana@eps.example --password "$PWD" --scheme jwt

# Verificación inmediata de identidad.
tecsas3 --json --no-input auth whoami

Cuando el CLI detecta que el token guardado (en keyring o en TECSAS3_TOKEN) comienza por eyJ — prefijo típico de un JWT codificado en base64 — y el esquema configurado es token, promueve automáticamente el esquema a jwt para emitir el header Bearer correcto. No hace falta cambiar --auth-scheme en runtime; la detección vive en cli/src/tecsas3_cli/runtime.py:Runtime.build.

Almacenamiento de credenciales

Los secretos nunca se persisten en config.toml. Viven en una de dos ubicaciones, según disponibilidad del backend keyring del sistema operativo:

Keyring del SO — entrada tecsas3-cli:<profile>:access (y :refresh si aplica). Es la ruta prioritaria: si el backend responde, se usa. Permite múltiples perfiles sin colisión de username.
Archivo fallback — ~/.tecsas3/credentials, JSON con la estructura {<profile>: {"access": "...", "refresh": "..."}}. Permisos 0600 (sólo lectura/escritura para el usuario); el directorio padre se crea con 0700.

El archivo de credenciales se inspecciona con ls -la ~/.tecsas3/ y se borra de forma segura eliminando el archivo. El CLI no expone un servicio central de logout server-side: la revocación real la hace el admin Django o, en el caso de JWT, la app rest_framework_simplejwt.token_blacklist.

# Inspección rápida del directorio de credenciales.
ls -la ~/.tecsas3/
# drwx------  user user  .
# drwx-xr-x  user user  ..
# -rw-------  user user  config.toml
# -rw-------  user user  credentials

# Rotación manual del token del perfil activo.
tecsas3 auth rotate

No copies ~/.tecsas3/credentials a un volumen compartido, ni lo subas a un repositorio. Si necesitas portar el perfil entre máquinas, vuelve a ejecutar tecsas3 auth login en el destino. Nunca expongas el token en logs, scripts o variables de shell persistidas en ~/.bashrc.

Sub-comandos de `tecsas3 auth`

Sub-comando	Descripción	Endpoint backend
`login`	Autentica con `--user` / `--password` (o `--api-key`) y guarda el token en el perfil activo. Acepta `--scheme token\|jwt`. Con `--no-input` requiere credenciales por env.	`POST /api/autenticar/` o `POST /api/token/`
`whoami`	Devuelve la identidad activa y el contexto de tenant: `profile`, `base_url`, `tenant`, `tenant_org`, `plan_id`, `auth_scheme`, `user`, `persona`.	`GET /persona/me/`
`logout`	Borra los tokens locales del perfil (`access` y `refresh`). No revoca el token server-side.	—
`rotate`	Borra los tokens locales y, con `--login`, vuelve a pedirlos. La revocación real requiere admin Django o JWT blacklist.	—

Ejemplos de uso

# Flujo completo: login, verificación y logout.
tecsas3 auth login --user ana@eps.example --password "$PWD"
tecsas3 --json --no-input auth whoami
tecsas3 auth logout

# Login con clave API pre-emitida y rotación inmediata.
tecsas3 auth login --api-key 9944b09199c62bcf9418ad846dd0... --scheme token
tecsas3 auth rotate --login

# Inspección de identidad en formato determinista para agentes.
tecsas3 --json --no-input auth whoami | jq '.user.email, .tenant, .auth_scheme'

Variables de entorno relevantes

Variable	Efecto
`TECSAS3_TOKEN`	Token literal. Si está presente, prevalece sobre el guardado en keyring. Recomendado para CI/CD con secretos efímeros.
`TECSAS3_USER`	Consumida por `tecsas3 auth login` si no se pasa `--user`.
`TECSAS3_PASSWORD`	Consumida por `tecsas3 auth login` si no se pasa `--password` y se está en modo no interactivo.
`TECSAS3_AUTH_SCHEME`	`token` (por defecto) o `jwt`. La auto-detección por prefijo `eyJ` puede sobrescribirlo en runtime.
`TECSAS3_PROFILE`	Perfil de configuración del que se leen los demás valores (base_url, tenant, etc.).

Buenas prácticas

Un perfil por entorno — usa --profile dev, --profile prod, --profile staging y no mezcles tokens entre ellos.
Rotación periódica — al menos cada 90 días para DRF Token; el refresh de JWT se puede rotar sin re-login hasta que expire.
No combines --debug con --redact-phi=false en producción — la redacción PHI está activa por defecto en logs stderr para evitar fugas accidentales de nombres, cedula o diagnostico.
En CI, exporta TECSAS3_TOKEN y NO_COLOR=1 — evita keyring (que requiere TTY) y mantiene los logs limpios.

Troubleshooting

Verifica que el esquema (--scheme) coincide con el del backend. Si el servidor migró de DRF Token a JWT, el flag --scheme token seguirá mandando Authorization: Token ... y el backend lo rechazará aunque la contraseña sea válida.

# Inspección rápida del esquema efectivo.
tecsas3 --json --no-input auth whoami 2>&1 | jq '.auth_scheme'

# Forzar esquema explícito.
tecsas3 auth login --user ana@eps.example --password "$PWD" --scheme jwt

`Keyring backend not available` en CI

El backend keyring requiere un TTY y un servicio de sistema (gnome-keyring, kwallet, Keychain). En runners de CI no hay ninguno de los dos. Soluciones:

# 1. Exportar el token directamente (recomendado en CI).
export TECSAS3_TOKEN=eyJhbGciOiJIUzI1NiIs...

# 2. Si necesitas el archivo fallback, asegúrate de que existe el directorio.
mkdir -p ~/.tecsas3 && chmod 0700 ~/.tecsas3
tecsas3 auth login --user ci-bot --password "$CI_PWD"

`AuthError (exit 3)` al primer comando del día

El token DRF Token no expira por sí solo pero puede ser revocado por el admin. El JWT expira según ACCESS_TOKEN_LIFETIME (configurado en SIMPLE_JWT). Si recibes Token expired at ..., rota:

# Re-login rápido.
tecsas3 auth rotate --login

Token detectado como `token` cuando es JWT

Si el esquema configurado en config.toml es token pero el token guardado empieza por eyJ, el runtime auto-promueve a jwt. Si aún así el backend responde 401, fuerza el esquema en la línea de comando:

tecsas3 --auth-scheme jwt --json --no-input paciente list

Inspección del perfil y el token

# Ver qué perfil y qué esquema están activos.
tecsas3 config show --json --no-input | jq '.profile, .auth_scheme, .tenant'

# Inspeccionar (con cuidado) el token guardado.
python3 -c "import json; d=json.load(open('$HOME/.tecsas3/credentials')); print(list(d.keys()))"

Integración con agentes de IA

La combinación --json --no-input + credenciales vía env permite que cualquier agente (claude-code, opencode, mcode, pi, hermes) opere el CLI sin intervención humana.

# Patrón de invocación determinista.
TECSAS3_TOKEN="$SECRET" NO_COLOR=1 tecsas3 --json --no-input <recurso> <acción>

# Agente invocando el CLI (ejemplo conceptual en pseudocódigo).
result = subprocess.check_output([
    "tecsas3", "--json", "--no-input", "auth", "whoami"
], env={**os.environ, "TECSAS3_TOKEN": token})
info = json.loads(result)

Los agentes deben:

Capturar siempre exit_code — los TecsaError se serializan a stderr con code, message, hint y request_id.
Preferir --json sobre --format yaml|csv — el parseo es 1:1 sin ambigüedades.
Evitar --debug en producción — filtra PHI al contexto del agente.
Rotar tokens vía auth rotate --login cuando se detecte exit 3 repetido.

Rotación de credenciales en flota

Para rotar tokens en muchos hosts a la vez:

# 1. Generar un nuevo token desde el admin Django.
# 2. Exportarlo a todos los hosts.
ansible all -m copy -a "src=./new_token dest=~/.tecsas3/credentials mode=0600"
# 3. Forzar recarga (cada proceso CLI es nuevo; no hay daemon).
ansible all -a "tecsas3 --json --no-input auth whoami"

Siguientes pasos

Aprende a configurar el tenant activo y los perfiles.
Revisa la tabla completa de códigos de salida para scripting.
Consulta la redacción PHI activa por defecto en logs.
Consulta la referencia de API auth para endpoints relacionados.

Empezar

Conceptos

Guías

Soporte

Esquemas de autenticación

Almacenamiento de credenciales

Sub-comandos de `tecsas3 auth`

Ejemplos de uso

Variables de entorno relevantes

Buenas prácticas

Troubleshooting

`Keyring backend not available` en CI

`AuthError (exit 3)` al primer comando del día

Token detectado como `token` cuando es JWT

Inspección del perfil y el token

Integración con agentes de IA

Rotación de credenciales en flota

Siguientes pasos

​Esquemas de autenticación

​Almacenamiento de credenciales

​Sub-comandos de tecsas3 auth

​Ejemplos de uso

​Variables de entorno relevantes

​Buenas prácticas

​Troubleshooting

​Login fallido (401) con credenciales correctas

​Keyring backend not available en CI

​AuthError (exit 3) al primer comando del día

​Token detectado como token cuando es JWT

​Inspección del perfil y el token

​Integración con agentes de IA

​Rotación de credenciales en flota

​Siguientes pasos

Esquemas de autenticación

Almacenamiento de credenciales

Sub-comandos de `tecsas3 auth`

Ejemplos de uso

Variables de entorno relevantes

Buenas prácticas

Troubleshooting

`Login fallido (401)` con credenciales correctas

`Keyring backend not available` en CI

`AuthError (exit 3)` al primer comando del día

Token detectado como `token` cuando es JWT

Inspección del perfil y el token

Integración con agentes de IA

Rotación de credenciales en flota

Siguientes pasos