Referencia de la API

Base: https://api.rempar.org/v1. JSON en todas partes. Las respuestas correctas van envueltas en {"data": ...}, los errores en {"error": {"code": "...", "message": "..."}}. Autenticación mediante token Bearer propio de cada dispositivo.

La API es de conocimiento cero: nunca recibe contraseñas ni contenido en claro. Los clientes de terceros son bienvenidos siempre que respeten el protocolo v1.

Salud

GET /v1/health
→ { "data": { "status": "ok", "release": "1.1.0" } }

Autenticación

Método Ruta Cuerpo Respuesta
POST /auth/prelogin {email} {kdf, kdf_salt}. Sal ficticia determinista si el correo es desconocido.
POST /auth/register {email, auth_key, kdf, kdf_salt, device} 201 {status: "verification_sent"}. Se envía un código de seis dígitos por correo electrónico.
POST /auth/verify-email {email, code} {}
POST /auth/login {email, auth_key, device, totp?, code?} {tokens, device_id, vault_key_sealed?}. Error totp_required (403) si la 2FA está activa y falta el código. Después email_code_required (403): se envía por e-mail un código de seis cifras que debe devolverse en code para obtener los tokens (10 min, 5 intentos).
POST /auth/refresh {refresh_token} {access_token, refresh_token, ...}. Rotación; una reutilización revoca el dispositivo.
POST /auth/logout Revoca el dispositivo actual.
POST /auth/recover {email, recovery_auth, totp?} Prueba del kit de emergencia: devuelve {vault_key_recovery, recovery_token} (15 min). totp_required si la 2FA está activa.
POST /auth/recover/complete {email, recovery_token, auth_key, kdf, kdf_salt, vault_key_sealed, device} Nueva contraseña maestra: sustituye la clave de autenticación y la clave de la bóveda vuelta a sellar, revoca todos los demás dispositivos y conecta este ({tokens, device_id, vault_key_sealed}).

device: {name, platform, client_id} donde client_id es un UUID elegido por el cliente, estable para este dispositivo.

kdf: {"algo": "argon2id", "m": 65536, "t": 3, "p": 4}. Los clientes rechazan parámetros más débiles que m=19456, t=2, p=1.

Cuenta

Método Ruta Descripción
GET /account Correo electrónico, estado 2FA, revisión de la bóveda, suscripción {plan, active, until}.
GET /account/subscription Solo la suscripción.
POST /account/password Sustituye auth_key tras un cambio de contraseña maestra. El cliente vuelve a publicar primero la clave de la bóveda resellada.
GET /account/devices Dispositivos activos.
DELETE /account/devices/{id} Revoca un dispositivo.
POST /account/totp/setup Genera un secreto y devuelve {secret, otpauth_url}.
POST /account/totp/enable {code}: activa la 2FA.
POST /account/totp/disable {code}: desactiva la 2FA.

Bóveda

Método Ruta Descripción
PUT /vault/key {vault_key_sealed, vault_key_recovery?}: solo blobs sellados, sustituidos de forma atómica. Siempre autorizado (restauración).
GET /vault/items?since=<revision>&limit=500 {items: [{id, revision, deleted, blob, updated_at}], revision}. Requiere una suscripción activa.
POST /vault/items {base_revision, items: [{id, blob|null}]} → {revision, conflicts: []}. blob: null elimina (lápida). Si base_revision está obsoleta, el servidor devuelve newer_items en lugar de escribir. Máximo 500 elementos por envío. Requiere una suscripción activa.

Suscripción

Cada cuenta empieza en trial durante 30 días. Las rutas de sincronización responden 402 subscription_required al expirar; la clave de la bóveda sellada sigue siendo legible para permitir una restauración. El cliente muestra "En espera" y continúa en local.

Códigos de error

Código HTTP Significado
invalid_credentials 401 Correo, clave o código incorrecto.
unauthenticated 401 Token ausente, caducado o dispositivo revocado.
email_unverified 403 Código de correo no introducido.
totp_required 403 Proporcione totp.
subscription_required 402 Suscripción Cloud caducada.
email_taken 409 Cuenta ya verificada con este correo.
stale_revision 409 Recupere primero los newer_items devueltos.
token_reused 401 Reutilización detectada, dispositivo revocado.

Límites de frecuencia

Preconexión 30/min, registro y verificación 10/min, inicio de sesión 15/min, actualización 30/min, rutas autenticadas 240/min por dispositivo.

Ejemplo

curl -s https://api.rempar.org/v1/auth/prelogin \
  -H 'Content-Type: application/json' \
  -d '{"email":"vous@example.org"}'

¿Una pregunta sin respuesta aquí? support@rempar.org