AppFreeticket · lu-ochenty · Jun 30, 2026 · Jun 30, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,14 @@ versioning follows [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+- **Self-service browser login:** `ft login` (no `--key`) now runs the OAuth 2.0
+  Device Authorization Grant (RFC 8628) — prints a code, opens the browser, polls
+  until you approve, and stores the minted session. Anyone with a FreeTicket
+  account can log in without a backend-issued API key. `ft login --key ft_live_…`
+  stays for headless CI. Consumes `POST /auth/device/code` + `POST /auth/device/token`
+  (free-admin#160).
+
 ## [0.4.0] - 2026-06-29
 
 ### Added

diff --git a/README.md b/README.md
@@ -51,17 +51,17 @@ ft --version
 ## Quickstart
 
 ```bash
-# 1. Issue an API key in the backend (server side):
-#    pnpm api:key you@example.com
-#    -> returns an ft_live_xxxxx key (shown only once)
+# 1. Log in through the browser (OAuth device flow). Prints a code, opens your
+#    browser, you approve, and the session is stored in ~/.freeticket/config.json.
+ft login
 
-# 2. Log in (stores the key in ~/.freeticket/config.json and verifies it)
-ft login --key ft_live_xxxxx
+# CI / automation: skip the browser with a backend-issued key instead.
+#   ft login --key ft_live_xxxxx
 
-# 3. Who am I, and which workspaces can I access?
+# 2. Who am I, and which workspaces can I access?
 ft whoami
 
-# 4. Start exploring
+# 3. Start exploring
 ft events list
 ft reports summary --period 30d
 ft sales list --status CONFIRMED --json
@@ -71,7 +71,7 @@ ft sales list --status CONFIRMED --json
 
 | Command | What it does | Minimum role |
 |---|---|---|
-| `ft login --key <key>` | Stores and verifies your API key | VIEWER |
+| `ft login` | Browser login (device flow); `--key <key>` for CI | VIEWER |
 | `ft whoami` | Active user and accessible workspaces | VIEWER |
 | `ft config` · `ft logout` | Show config (masked key) · remove key | — |
 | `ft events list` · `get <id>` | Workspace events | VIEWER |
@@ -170,7 +170,7 @@ CLI QA, and release/devops. See the [agents README](./.claude/agents/README.md).
 ## Requirements
 
 - Node.js **>= 20**
-- A FreeTicket API key (`ft_live_...`)
+- A FreeTicket account (`ft login` opens the browser; no API key needed)
 
 ## License
 

diff --git a/openapi.json b/openapi.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "FreeTicket B2B API",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "API REST B2B de FreeTicket para integraciones y el CLI. Autenticación por API key (header `Authorization: Bearer <key>` o `x-api-key`); el workspace activo se selecciona con el header `X-Workspace-Id`."
   },
   "servers": [
@@ -16,6 +16,82 @@
     }
   ],
   "paths": {
+    "/auth/device/code": {
+      "post": {
+        "operationId": "postAuthDeviceCode",
+        "tags": [
+          "auth"
+        ],
+        "summary": "Inicia el Device Authorization Grant (RFC 8628)",
+        "description": "Endpoint público (sin auth): bootstrap de credenciales del Device Authorization Grant (RFC 8628).",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Flujo iniciado: device_code (lo poll-ea el CLI) + user_code (lo aprueba el usuario en el browser).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceCodeResponse"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Demasiadas solicitudes desde la misma IP (anti-flood).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/auth/device/token": {
+      "post": {
+        "operationId": "postAuthDeviceToken",
+        "tags": [
+          "auth"
+        ],
+        "summary": "Poll del CLI: canjea el device_code por una API key al aprobar",
+        "description": "Endpoint público (sin auth): bootstrap de credenciales del Device Authorization Grant (RFC 8628).",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeviceTokenRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Aprobado: entrega la API key ft_live_… una sola vez y consume la fila.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceTokenResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Estado RFC 8628: authorization_pending | slow_down | expired_token | access_denied | invalid_request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceTokenError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/me": {
       "get": {
         "operationId": "getMe",
@@ -3463,6 +3539,130 @@
         ],
         "additionalProperties": false
       },
+      "DeviceCodeResponse": {
+        "type": "object",
+        "properties": {
+          "device_code": {
+            "type": "string"
+          },
+          "user_code": {
+            "type": "string"
+          },
+          "verification_uri": {
+            "type": "string"
+          },
+          "verification_uri_complete": {
+            "type": "string"
+          },
+          "expires_in": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "interval": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          }
+        },
+        "required": [
+          "device_code",
+          "user_code",
+          "verification_uri",
+          "verification_uri_complete",
+          "expires_in",
+          "interval"
+        ],
+        "additionalProperties": false
+      },
+      "DeviceTokenRequest": {
+        "type": "object",
+        "properties": {
+          "device_code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "grant_type": {
+            "type": "string",
+            "const": "urn:ietf:params:oauth:grant-type:device_code"
+          }
+        },
+        "required": [
+          "device_code"
+        ],
+        "additionalProperties": false
+      },
+      "DeviceTokenResponse": {
+        "type": "object",
+        "properties": {
+          "access_token": {
+            "type": "string"
+          },
+          "token_type": {
+            "type": "string",
+            "const": "Bearer"
+          },
+          "user": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string"
+              },
+              "role": {
+                "type": "string",
+                "enum": [
+                  "SUPER_ADMIN",
+                  "ADMIN",
+                  "STAFF",
+                  "VIEWER",
+                  "MINCULTURA"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "email",
+              "role"
+            ],
+            "additionalProperties": false
+          },
+          "workspaces": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Workspace"
+            }
+          }
+        },
+        "required": [
+          "access_token",
+          "token_type",
+          "user",
+          "workspaces"
+        ],
+        "additionalProperties": false
+      },
+      "DeviceTokenError": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "enum": [
+              "authorization_pending",
+              "slow_down",
+              "expired_token",
+              "access_denied",
+              "invalid_request"
+            ]
+          }
+        },
+        "required": [
+          "error"
+        ],
+        "additionalProperties": false
+      },
       "Event": {
         "type": "object",
         "properties": {

diff --git a/scripts/sync-openapi.ts b/scripts/sync-openapi.ts
@@ -1,11 +1,12 @@
 // Downloads the backend OpenAPI contract and regenerates the client.
-//   FT_OPENAPI_URL=https://admin.appfreeticket.com/api/v1/openapi.json pnpm sync-openapi
+// Defaults to production; point at a local backend with:
+//   FT_OPENAPI_URL=http://admin.localhost:3000/api/v1/openapi.json pnpm sync-openapi
 import { execSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
 
 const url =
   process.env.FT_OPENAPI_URL ??
-  "http://admin.localhost:3000/api/v1/openapi.json";
+  "https://admin.appfreeticket.com/api/v1/openapi.json";
 
 const res = await fetch(url);
 if (!res.ok) {