Autorización
El flujo es OAuth 2.0 Authorization Code con PKCE S256 obligatorio. Tu aplicación nunca ve
la contraseña ni la sesión de la persona: recibe tokens propios, que solo valen para lo que se
autorizó y que la persona puede anular cuando quiera.
Resumen del flujo
Sección titulada «Resumen del flujo»- Tu aplicación genera un
code_verifier, sucode_challengey unstate. - Abre el navegador en
GET /api/v1/oauth/authorizecon esos datos. - La plataforma lleva a la persona a su pantalla de consentimiento. Si no tiene sesión, entra o se registra y vuelve a esa pantalla.
- La persona ve el nombre de tu aplicación y los permisos que pides, y pulsa Autorizar o Cancelar.
- El navegador vuelve a tu dirección de retorno con
codeystate, o conerrorystate. - Tu aplicación comprueba el
statey cambia elcodey elcode_verifierpor un token de acceso y uno de refresco enPOST /api/v1/oauth/token. - Llama a
/api/v1/connect/…conAuthorization: Bearer <access_token>. - Cuando el token de acceso caduca, lo renueva con el de refresco, que rota en cada uso.
1. Preparar PKCE y state
Sección titulada «1. Preparar PKCE y state»| Valor | Cómo |
|---|---|
code_verifier |
Aleatorio criptográficamente seguro, de 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~ |
code_challenge |
BASE64URL(SHA256(code_verifier)) sin relleno =: siempre 43 caracteres |
state |
Aleatorio, obligatorio, de hasta 512 caracteres. Lo devolvemos intacto |
Genera los tres en cada intento y guárdalos solo en memoria hasta que vuelva la respuesta.
plain no se admite como método de PKCE.
Puedes comprobar tu implementación con el ejemplo del apéndice B de RFC 7636: el verificador
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk produce el reto
E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.
2. La dirección de retorno
Sección titulada «2. La dirección de retorno»Depende de cómo esté registrada tu aplicación, y el esquema decide la regla:
| Tipo de aplicación | redirect_uri |
Cómo se compara |
|---|---|---|
| De escritorio | http://127.0.0.1:{puerto}{ruta} o http://[::1]:{puerto}{ruta} |
El puerto es libre; la ruta debe ser una registrada, exacta |
| Alojada en la web | https://… completa |
Exactamente, carácter a carácter, como se registró |
Para una aplicación de escritorio:
- abre un servidor HTTP solo en la interfaz de loopback, en un puerto libre que te dé el
sistema operativo (puerto
0), justo antes de abrir el navegador, y ciérralo al recibir la respuesta; - usa la IP literal, nunca
localhost: no se admite (RFC 8252 §8.3); - la dirección no lleva consulta ni fragmento.
Abre la autorización en el navegador del sistema, no en una vista web incrustada en tu aplicación: en el navegador la persona ve la dirección real de la plataforma, usa su sesión y su gestor de contraseñas, y tu aplicación no puede leer lo que escribe.
3. Abrir la autorización
Sección titulada «3. Abrir la autorización»GET https://api.lectoresbeta.com/api/v1/oauth/authorize ?client_id=TU_CLIENT_ID &redirect_uri=http://127.0.0.1:53682/callback &response_type=code &scope=works:read works:write feedback:read credits:read &state=… &code_challenge=… &code_challenge_method=S256Codifica los parámetros como en cualquier URL (los espacios de scope, como %20 o +).
| Parámetro | Obligatorio | Valor |
|---|---|---|
client_id |
Sí | El que te dimos |
redirect_uri |
Sí | Ver el apartado anterior |
response_type |
Sí | code |
scope |
Sí | Permisos separados por espacios. Ver Permisos |
state |
Sí | Tu valor aleatorio |
code_challenge |
Sí | El reto PKCE |
code_challenge_method |
Sí | S256 |
La respuesta es un 302 a la pantalla de consentimiento. A partir de ahí no hay nada que hacer
hasta que el navegador vuelva a tu dirección de retorno.
Pide solo los permisos que tu aplicación usa. La persona los ve uno a uno antes de decidir.
Si algo está mal en la petición
Sección titulada «Si algo está mal en la petición»- Si el
client_idno existe o tu aplicación está desactivada, o laredirect_urino es una de las registradas, el navegador no vuelve a tu aplicación: la persona ve el error en la propia página (422, concodeINVALID_CONNECTED_APP_CLIENToINVALID_REDIRECT_URI). Redirigir ahí convertiría el endpoint en un redirector abierto. - Cualquier otro error vuelve a tu dirección de retorno con
error,error_descriptiony tustate:
error |
Cuándo |
|---|---|
unsupported_response_type |
response_type no es code |
invalid_request |
Falta state o pasa de 512 caracteres; PKCE ausente, no S256 o reto inválido |
invalid_scope |
Un permiso no existe, la lista está vacía o pide algo que tu aplicación no tiene permitido |
access_denied |
La persona pulsó Cancelar |
4. Lo que hace la persona
Sección titulada «4. Lo que hace la persona»- Si no tiene sesión, entra o crea su cuenta y vuelve a la pantalla de consentimiento.
- Para autorizar necesita tener la cuenta activada con el enlace que le enviamos por correo. Si no lo está, la pantalla se lo pide y puede volver a pulsar Autorizar después.
- La petición de autorización caduca a los 10 minutos. Si caduca, la pantalla le pide volver
a empezar desde tu aplicación: inicia el flujo de nuevo, con verificador y
statenuevos. - La pregunta se hace siempre, aunque la persona ya hubiera autorizado tu aplicación. Autorizar de nuevo suma los permisos pedidos a los que ya tenía.
5. Recibir la respuesta
Sección titulada «5. Recibir la respuesta»GET http://127.0.0.1:53682/callback?code=…&state=…- Comprueba que
statees exactamente el que enviaste. Si no, descarta la respuesta. - Si llega
error, no hay código.access_deniedes una respuesta normal: la persona dijo que no. - Responde al navegador con una página sencilla («Ya puedes volver a la aplicación») y cierra el servidor local.
El código dura 60 segundos y sirve una sola vez. Canjéalo en cuanto llegue.
6. Cambiar el código por tokens
Sección titulada «6. Cambiar el código por tokens»curl -X POST https://api.lectoresbeta.com/api/v1/oauth/token \ -d grant_type=authorization_code \ -d client_id=TU_CLIENT_ID \ -d code=EL_CODIGO \ -d redirect_uri=http://127.0.0.1:53682/callback \ -d code_verifier=TU_VERIFICADOREl cuerpo va como formulario (application/x-www-form-urlencoded), no como JSON, y la
redirect_uri tiene que ser la misma que usaste al abrir la autorización.
{ "access_token": "8f2c…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "41d9…", "scope": "works:read works:write feedback:read credits:read"}scope es lo que la persona concedió: compruébalo en vez de suponerlo.
Si el código se presenta dos veces, damos por hecho que se ha filtrado y revocamos todos los tokens emitidos con él. Tu aplicación tendría que volver a pedir autorización.
7. Usar el token de acceso
Sección titulada «7. Usar el token de acceso»curl https://api.lectoresbeta.com/api/v1/connect/me \ -H "Authorization: Bearer EL_ACCESS_TOKEN"Los tokens son opacos: no intentes decodificarlos ni deducir nada de su forma. Solo valen en
/api/v1/connect/…; en cualquier otra ruta de la API reciben 401.
8. Renovar: rotación de tokens de refresco
Sección titulada «8. Renovar: rotación de tokens de refresco»curl -X POST https://api.lectoresbeta.com/api/v1/oauth/token \ -d grant_type=refresh_token \ -d client_id=TU_CLIENT_ID \ -d refresh_token=EL_REFRESH_TOKENLa respuesta tiene la misma forma que el canje, con un par nuevo. El token de refresco que enviaste ya no vale.
Dos reglas que hay que respetar sí o sí:
- Guarda el nuevo token de refresco antes de hacer nada más. Si lo pierdes, la persona tendrá que volver a autorizar.
- No renueves dos veces a la vez con el mismo token. Si tu aplicación tiene varios hilos o ventanas, serializa la renovación. Un token de refresco ya usado que se presenta de nuevo significa que dos partes lo tienen, y en ese caso revocamos toda la familia de tokens de esa autorización, también el par que acabas de recibir.
Puedes pedir menos permisos al renovar con scope (por ejemplo -d scope=works:read); nunca
más de los concedidos (invalid_scope).
9. Cerrar sesión: revocar
Sección titulada «9. Cerrar sesión: revocar»curl -X POST https://api.lectoresbeta.com/api/v1/oauth/revoke \ -d client_id=TU_CLIENT_ID \ -d token=EL_REFRESH_TOKENRevocar cualquiera de los dos tokens revoca todos los tokens de esa autorización. La respuesta
es 200 aunque el token no exista (RFC 7009).
La autorización en sí se mantiene: tu aplicación sigue apareciendo en la lista de aplicaciones conectadas de la persona, y para volver a entrar pasará por el navegador otra vez.
Duración de cada cosa
Sección titulada «Duración de cada cosa»| Qué | Dura |
|---|---|
| Petición de autorización | 10 minutos |
| Código de autorización | 60 segundos, un solo uso |
| Token de acceso | 1 hora |
| Token de refresco | 30 días, un solo uso (rota al renovar) |
Mientras la persona use tu aplicación al menos una vez cada 30 días, no tendrá que volver a autorizar.
Qué deja sin acceso a tu aplicación
Sección titulada «Qué deja sin acceso a tu aplicación»Todo esto surte efecto en la siguiente petición, sin esperar a que nada caduque:
- la persona retira el acceso en Configuración → Aplicaciones conectadas;
- desactivamos tu aplicación;
- la cuenta de la persona queda bloqueada o se borra;
- se detecta la reutilización de un código o de un token de refresco.
Cambiar la contraseña no desconecta las aplicaciones: no la conocen.
Qué hacer: ante un 401 con WWW-Authenticate: Bearer error="invalid_token", renueva una
vez. Si la renovación responde invalid_grant, la autorización ya no vale: borra los tokens
guardados y vuelve a empezar el flujo.
Dónde guardar los tokens
Sección titulada «Dónde guardar los tokens»- Aplicación de escritorio: en el almacén seguro del sistema operativo (Keychain en macOS, Credential Manager en Windows, Secret Service / libsecret en Linux). Nunca en ficheros de configuración en claro.
- Aplicación alojada en la web: en tu servidor, cifrados y asociados a tu usuario. Nunca en el navegador.
- Nunca en logs, informes de errores ni analíticas: ni los tokens, ni el código, ni el verificador.
Límites
Sección titulada «Límites»Los tres endpoints de /oauth comparten un límite de 60 peticiones cada 5 minutos por
dirección IP. Una aplicación que se comporta bien hace unas pocas por hora. Al superarlo se
responde 429 con Retry-After.
Ejemplo completo (aplicación de escritorio)
Sección titulada «Ejemplo completo (aplicación de escritorio)»Un ejemplo mínimo en Python, solo con la biblioteca estándar, para entender las piezas. No es código de producción: no guarda los tokens en el almacén seguro ni gestiona reintentos.
import base64, hashlib, http.server, json, secrets, urllib.parse, urllib.request, webbrowser
API = "https://api.lectoresbeta.com/api/v1"CLIENT_ID = "TU_CLIENT_ID"SCOPE = "works:read works:write feedback:read credits:read"
verifier = secrets.token_urlsafe(64)[:96]challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()state = secrets.token_urlsafe(16)received = {}
class Callback(http.server.BaseHTTPRequestHandler): def do_GET(self): query = urllib.parse.urlparse(self.path).query received.update({k: v[0] for k, v in urllib.parse.parse_qs(query).items()}) self.send_response(200) self.send_header("Content-Type", "text/html; charset=utf-8") self.end_headers() self.wfile.write("Ya puedes volver a la aplicación.".encode())
def log_message(self, *args): pass
server = http.server.HTTPServer(("127.0.0.1", 0), Callback)redirect_uri = f"http://127.0.0.1:{server.server_port}/callback"
webbrowser.open(f"{API}/oauth/authorize?" + urllib.parse.urlencode({ "client_id": CLIENT_ID, "redirect_uri": redirect_uri, "response_type": "code", "scope": SCOPE, "state": state, "code_challenge": challenge, "code_challenge_method": "S256",}))server.handle_request()
assert received.get("state") == state, "state no coincide"assert "code" in received, f"sin código: {received}"
form = urllib.parse.urlencode({ "grant_type": "authorization_code", "client_id": CLIENT_ID, "code": received["code"], "redirect_uri": redirect_uri, "code_verifier": verifier,}).encode()with urllib.request.urlopen(urllib.request.Request(f"{API}/oauth/token", data=form)) as response: tokens = json.load(response)
print(tokens["scope"], tokens["expires_in"])