Referencia de la API
Todos los endpoints de la API de administración del puente de SQLly Embedded, generados a partir de su documento OpenAPI (swagger.json), además de los endpoints de vinculación de sqlly.app.
El puente SQLly en modo integrado expone esta API en su listener de gestión (--manage-bind, predeterminado 127.0.0.1:8445). Tu aplicación web lo llama desde su lado del servidor para guardar perfiles de conexión, probar conexiones, emitir tokens de lanzamiento para los usuarios con sesión iniciada, vigilar los asientos y leer o cambiar el estado de la licencia.
Cada /manage/... llamada necesita Authorization: Bearer <manage token> (del puente --manage-token, al menos 16 caracteres). Los cuerpos van en JSON en ambos sentidos, con un máximo de 8 MB (se rechaza con 413 too_large en cuanto se pasa del límite). Los segmentos de la ruta y los valores de la cadena de consulta se decodifican con codificación porcentual; un escape no válido es 400 bad_request. Los errores siempre son { "error": "<code>", "message": "<sentence>" }, además de problems cuando un documento de credenciales no es válido. La API no envía encabezados CORS: mantenla en loopback o en una red privada y nunca la expongas a navegadores, porque los perfiles contienen contraseñas de bases de datos.
La Linking las operaciones no están en el puente: son los puntos finales públicos de sqlly.app que una app de administración usa para vincular una instalación a una licencia sin copiar una clave. Su servidor es sqlly.app.
Guía: sqlly.app/docs/embedded
Convenciones
- Autenticación:
Authorization: Bearer <manage token>en cada/manage/…llamada. Un token ausente o incorrecto es401 unauthorized./healthzy los endpoints de enlace de sqlly.app no necesitan ninguno. - Errores son
{ "error": "<code>", "message": "<sentence>" }. Ramifica enerror; muestramessage. Los documentos de credenciales no válidos añadenproblems, una cadena por error. - Cuerpos son JSON, 8 MB como máximo. El límite se aplica a medida que llega el cuerpo: el puente responde
413 too_largeel momento en que se pasa y nunca almacena más en búfer. Un cuerpo que tarda más de 30 segundos en llegar es408 timeout. Cualquier cosa que no se pueda analizar es400 bad_json, y una ruta desconocida es404 not_found. - Segmentos de ruta y valores de consulta se decodifican con codificación porcentual, así que codifica en la URL los IDs de usuario y las marcas de tiempo (
DELETE /manage/seats/a%2Fblibera al usuarioa/b). Un escape no válido o un resultado que no sea UTF-8 es400 bad_request. - Nombres de campos están en camelCase en los payloads de la propia API. Dentro de un documento de credenciales siguen el formato de credencial (
sql_auth_accounts,trust_server_certificate).
Endpoints
- GET
/healthz - GET
/manage/status - POST
/manage/license/checkin - PUT
/manage/license - DELETE
/manage/license - GET
/manage/engines - GET
/manage/profiles - GET
/manage/profiles/{id} - PUT
/manage/profiles/{id} - DELETE
/manage/profiles/{id} - POST
/manage/tokens - GET
/manage/seats - DELETE
/manage/seats/{user} - POST
/manage/test-connection - GET
/manage/queries - POST
/api/embedded/links - POST
/api/embedded/links/token - GET
/api/embedded/public-key
Estado
Sonda de actividad, sin token.
/healthz
sin token
Sonda de actividad
Responde tan pronto como el listener de administración esté activo. No necesita token; úsalo desde los scripts de inicio y las comprobaciones de estado del servicio.
- 200
- La API de gestión está a la escucha.
Ejemplo de respuesta 200
{
"ok": true
}
Licencia
La licencia con la que funciona el puente: estado, registro, vinculación y desvinculación.
/manage/status
Estado del puente y de la licencia
Todo lo que necesita una pantalla de administrador: el estado de la licencia y de dónde proviene, las asignaciones que lleva la concesión firmada, asientos en uso, sesiones abiertas y la URL del proxy que usan los navegadores.
- 200
- Estado actual.
- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
{
"version": "1.1.0",
"instanceId": "b5e1c0f2-7d3a-4c8e-9a61-0f2d4b7e9c13",
"mode": "connected",
"license": {
"state": "ok",
"source": "linked",
"licenseId": "emb_Q2x0b3VkU3FsbHkxMjM0NTY3",
"plan": "embedded-25",
"planName": "SQLly Embedded 25",
"status": "active",
"seats": 25,
"sessionsPerSeat": 4,
"instances": 1,
"domain": "portal.example.com",
"periodEnd": "2027-10-14T00:00:00+00:00",
"graceEnd": null,
"daysRemaining": 365,
"lastCheckinAt": "2026-10-14T15:00:02Z",
"staleAt": "2026-10-14T15:40:02Z",
"licenseFile": null,
"message": null,
"fromCache": false,
"features": [
"embedded",
"unlimited-connections",
"all-engines",
"test-connection"
]
},
"seatsUsed": 3,
"activeSessions": 4,
"proxyUrl": "wss://portal.example.com/sqlly/proxy",
"allowLocalhostOrigins": false,
"storeUrl": "https://sqlly.app",
"allowFileEngines": false
}
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license/checkin
Conecta con sqlly.app ahora
Licencias conectadas y vinculadas: hace el registro de inmediato en lugar de esperar el ciclo de 20 minutos. Licencias sin conexión: vuelve a leer el archivo de licencia y nunca toca la red. En cualquier caso, la respuesta es el estado tras el intento; si falla, el estado no cambia.
- 200
- Estado después del registro.
- 401
unauthorized: falta el token de administración o es incorrecto.- 409
not_linked: el puente no tiene licencia, no hay nada que reportar.- 422
license_file_invalid(sin conexión): falta el archivo, está dañado o está firmado con otra clave.- 502
store_unreachableogrant_invalid: no se pudo acceder a sqlly.app, o su respuesta no superó la verificación.
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Ejemplo de respuesta 409
{
"error": "not_linked",
"message": "this bridge is not linked to a license yet"
}
/manage/license
Instalar una clave de licencia vinculada
Proporciona un puente que se inició sin --license-key / --license-file su clave en tiempo de ejecución (normalmente la clave que tu app de administración acaba de recoger de sqlly.app mediante el flujo de enlace). El puente se registra primero con ella y la guarda (<state-dir>/license-key, modo 0600) solo si sqlly.app responde con una concesión verificada; desde ese momento funciona como puente conectado, y la clave se reutiliza tras los reinicios. Si algo falla, nada cambia: la clave en uso sigue sirviendo hasta que la nueva quede verificada. Si sustituyes una clave vinculada por otra de otra licencia, se libera el cupo de instancias de la licencia anterior cuando la nueva se verifica; una clave regenerada de la misma licencia reutiliza la fila de instancia del almacén.
Cuerpo de la solicitud (LinkLicenseRequest)
{
"licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
- 200
- Vinculado. El estado ahora muestra
license.source: linked. - 400
invalid_license_key: clave vacía, mal formada, desconocida o revocada.- 401
unauthorized: falta el token de administración o es incorrecto.- 409
license_from_flag: el puente se inició con--license-keyo--license-file, por lo que su licencia no se gestiona a través de esta API.- 502
store_unreachable: no se pudo acceder a sqlly.app o su respuesta no superó la verificación.
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license
Desvincular esta instalación
Libera la ranura de instancia de este puente, revoca su clave en sqlly.app (en la medida de lo posible), elimina la clave almacenada, cierra todas las sesiones abiertas y devuelve el puente a unlicensed.
- 204
- Desvinculado.
- 401
unauthorized: falta el token de administración o es incorrecto.- 404
not_linked: no hay ninguna clave vinculada almacenada.- 409
license_from_flag: el puente se inició con--license-keyo--license-file, por lo que su licencia no se gestiona a través de esta API.
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Motores
Los motores de base de datos que acepta el formato de credenciales, para que tu interfaz nunca tenga la lista fija en el código.
/manage/engines
Motores que acepta el formato de credenciales
Cada motor de base de datos que SQLly soporta, con el engine id para escribir en un documento de credenciales, su puerto predeterminado, si server es una ruta de archivo, y los authentication.type valores que acepta.
- 200
- Los motores.
- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
[
{
"id": "sql-server",
"name": "Microsoft SQL Server",
"defaultPort": 1433,
"fileBased": false,
"authentication": [
"sql-login",
"integrated",
"entra-browser",
"entra-device-code"
]
},
{
"id": "postgres",
"name": "PostgreSQL",
"defaultPort": 5432,
"fileBased": false,
"authentication": [
"sql-login"
]
},
{
"id": "sqlite",
"name": "SQLite",
"defaultPort": 0,
"fileBased": true,
"authentication": [
"none"
]
}
]
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Perfiles
Un perfil es un documento de credenciales de SQLly con nombre: las conexiones (y etiquetas) que ve un grupo de usuarios. El puente es el almacén de referencia; los secretos nunca llegan al navegador.
/manage/profiles
Listar perfiles
Cada perfil almacenado sin sus credenciales.
- 200
- Los perfiles.
- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
[
{
"id": "analysts",
"name": "Analysts",
"connections": 2,
"updatedAt": "2026-10-14T15:02:11Z"
}
]
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Leer un perfil
El perfil con su documento de credenciales completo, secretos incluidos: el llamador es tu aplicación confiable del lado del servidor.
- id
- ruta · cadena que coincide con ^[A-Za-z0-9_-]{1,64}$ · obligatorio - Tu id para el perfil.
- 200
- El perfil.
- 400
invalid_profile_id: los ids son de 1 a 64 deA-Z a-z 0-9 _ -.- 401
unauthorized: falta el token de administración o es incorrecto.- 404
unknown_profile: ningún perfil tiene ese id.
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Ejemplo de respuesta 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
Crear o reemplazar un perfil
Almacena el perfil bajo id (crear o reemplazar). El documento de credenciales se valida por completo antes de escribir nada: cada problema que detecta el analizador se devuelve en problems, y un documento no válido no cambia nada. Un documento que contenga un motor basado en archivos (SQLite, DuckDB) es rechazado de la misma manera a menos que el puente se ejecute con --allow-file-engines true, porque ese tipo de conexión da a sus usuarios acceso a archivos en el host puente. Las sesiones ya abiertas conservan el catálogo con el que empezaron; los cambios se aplican en el próximo inicio.
- id
- ruta · cadena que coincide con ^[A-Za-z0-9_-]{1,64}$ · obligatorio - Tu id para el perfil.
Cuerpo de la solicitud (PutProfileRequest)
{
"name": "Analysts",
"credentials": {
"format": "sqlly-credentials",
"version": 1,
"clients": [
{
"name": "Northwind Traders",
"color": "#1E88E5"
}
],
"environments": [
{
"name": "Production",
"color": "#C62828",
"safety": {
"only_allow_select": true
}
}
],
"sql_auth_accounts": [
{
"name": "Reader",
"username": "reader",
"password": "…"
}
],
"connections": [
{
"name": "Northwind",
"engine": "sql-server",
"server": "sql01.internal",
"database": "Northwind",
"environment": "production",
"client": "Northwind Traders",
"authentication": {
"type": "sql-login",
"account": "Reader"
},
"tls": {
"encrypt": true,
"trust_server_certificate": true
}
},
{
"name": "Warehouse",
"engine": "postgres",
"server": "dw.internal",
"database": "dw",
"environment": "production",
"client": "Northwind Traders",
"authentication": {
"type": "sql-login",
"account": "Reader"
},
"tls": {
"mode": "verify-full"
}
}
]
}
}
- 200
- Almacenado.
- 400
invalid_profile(conproblems: problemas del analizador, o cada motor basado en archivos mientras--allow-file-enginesestá apagado), oinvalid_profile_id.- 401
unauthorized: falta el token de administración o es incorrecto.- 500
storage: no se pudo escribir el directorio de estado.
Ejemplo de respuesta 400
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Eliminar un perfil
Elimina el perfil. Las sesiones abiertas mantienen el catálogo con el que empezaron; los nuevos tokens de lanzamiento para él se rechazan con unknown_profile.
- id
- ruta · cadena que coincide con ^[A-Za-z0-9_-]{1,64}$ · obligatorio - Tu id para el perfil.
- 204
- Eliminado.
- 400
invalid_profile_id: los ids son de 1 a 64 deA-Z a-z 0-9 _ -.- 401
unauthorized: falta el token de administración o es incorrecto.- 404
unknown_profile: ningún perfil tiene ese id.
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Ejemplo de respuesta 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
Lanzar
Los tokens de lanzamiento abren SQLly para un usuario con un perfil. Los asientos son usuarios concurrentes.
/manage/tokens
Generar un token de lanzamiento
Crea un token de corta duración que abre SQLly para user con profile, opcionalmente directamente en las pestañas de consulta (open, el contexto de lanzamiento). Coloca el proxyUrl y token devuelto en la página que carga SQLly (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). El token puede reutilizarse hasta que expire (recarga de página), y el perfil se captura en el momento de la generación.
Un usuario ocupa un asiento mientras tenga una sesión abierta o un token sin caducar. Emitir un token para un usuario que ya ocupa un asiento nunca falla por el límite de asientos; emitir uno para un usuario nuevo falla con seat_limit cuando cada asiento de la licencia está en uso, contando usuarios en cada puente de la licencia.
Cuerpo de la solicitud (MintTokenRequest)
{
"user": "dana.analyst",
"profile": "analysts",
"open": {
"connection": "Shop",
"database": "sales",
"title": "Big orders",
"script": "SELECT *\nFROM orders\nWHERE total > @min_total",
"parameters": {
"min_total": 500
},
"cursor": {
"line": 3,
"column": 7
}
}
}
- 201
- El token.
- 400
invalid_user(vacío o con espacios en blanco, 128 caracteres como máximo),invalid_profile(el perfil almacenado ya no se valida, o contiene un motor basado en archivos mientras--allow-file-enginesestá apagado), oinvalid_open(el contexto de lanzamiento nombra una conexión desconocida, un campo o tipo desconocido, un nombre o valor de parámetro incorrecto, un cursor fuera de rango, o pasa un límite;problemslista cada error con su ruta, por ejemploopen[1].cursor: …).- 401
unauthorized: falta el token de administración o es incorrecto.- 404
unknown_profile: ningún perfil tiene ese id.- 409
seat_limit: cada asiento está en uso. Libera uno (DELETE /manage/seats/{user}) o compra un plan más grande.- 503
license_not_ok: la licencia no estáokograce(obsoleto, caducado, revocado, no admitido, con dominio que no coincide o sin licencia). El mensaje indica cuál.
Ejemplo de respuesta 201
{
"token": "elt_q3J0n8w2Zx5rVb1kTq9yLs4dHf7cMa6p",
"expiresAt": "2026-10-14T15:12:11Z",
"proxyUrl": "wss://portal.example.com/sqlly/proxy",
"user": "dana.analyst",
"profile": "analysts",
"seatsUsed": 3,
"seats": 25,
"openTabs": 0
}
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats
Asientos en uso
Usuarios con asiento en este puente, con sus sesiones abiertas y sus tokens activos. seatsUsed también cuenta a los usuarios que sqlly.app notificó en otros puentes de la misma licencia.
- 200
- Uso de asientos.
- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
{
"seats": 25,
"seatsUsed": 2,
"users": [
{
"user": "dana.analyst",
"activeSessions": 1,
"tokens": 1,
"since": "2026-10-14T15:02:11Z"
},
{
"user": "sam.support",
"activeSessions": 2,
"tokens": 1,
"since": "2026-10-14T14:40:03Z"
}
]
}
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
Liberar el asiento de un usuario
Revoca los tokens del usuario y cierra sus sesiones, liberando el asiento de inmediato. Llámalo cuando un usuario cierre sesión en tu aplicación o pierda el acceso. Liberar a un usuario sin asiento no es un error. El segmento de la ruta va decodificado (percent-decoded): a%2Fb libera al usuario a/b.
- usuario
- ruta · cadena · requerido - El ID de usuario para el que acuñaste tokens (codificado en URL).
- 204
- Liberado.
- 400
bad_request: el segmento no es una codificación porcentual válida.- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Conexiones
Comprueba que una conexión funciona antes de que alguien la use.
/manage/test-connection
Probar una conexión
Ejecuta un motor desechable contra un documento de credenciales que contiene exactamente una conexión y ejecuta una consulta trivial. Los fallos de conexión se informan como ok: false con el propio mensaje del motor (HTTP 200); solo un documento inutilizable es un error HTTP.
Cuerpo de la solicitud (TestConnectionRequest)
{
"credentials": {
"format": "sqlly-credentials",
"version": 1,
"connections": [
{
"name": "Northwind",
"engine": "sql-server",
"server": "sql01.internal",
"database": "Northwind",
"authentication": {
"type": "sql-login",
"username": "reader",
"password": "…"
},
"tls": {
"encrypt": true,
"trust_server_certificate": true
}
}
]
}
}
- 200
- El resultado, con éxito o no.
- 400
invalid_profile: el documento no es válido, no contiene exactamente una conexión o contiene un motor basado en archivos mientras--allow-file-enginesestá apagado (verproblems).- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
{
"ok": true,
"elapsedMs": 212,
"message": "Connected: SQL Server 17.0"
}
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Auditoría
El historial de auditoría de consultas: cada consulta y edición de filas que ejecutó una sesión, quién la ejecutó, en qué conexión y cómo terminó. Se conserva en memoria y en <state-dir>/queries.jsonl (Texto SQL incluido) a menos que el puente se ejecute con --query-log false.
/manage/queries
Registro de auditoría de consultas
Cada consulta y edición de fila que ejecutaron las sesiones del puente, más recientes primero: el usuario y perfil del token de lanzamiento, la conexión que nombró (nombre, servidor, motor, base de datos), el texto SQL (recortado a 64 KiB, ver sqlTruncated), cuándo comenzó, su estado y su duración, y el error del motor si falló. Las peticiones que siguen en ejecución se listan con el estado running; una solicitud rechazada porque la licencia no estaba en orden es failed con el mensaje de la licencia; lo que se estaba ejecutando cuando se cerró una sesión es cancelled con error session closed.
El puente conserva las últimas --query-log-max-entries entradas (20 000 por defecto) se guardan en memoria y en <state-dir>/queries.jsonl, así que el registro sobrevive a un reinicio. Con --query-log false no se registra nada y la respuesta es { "enabled": false, "queries": [] }.
- límite
- consulta · entero - Entradas a devolver, limitadas a 1-1000.
- usuario
- consulta · cadena - Solo este ID de usuario (coincidencia exacta, codificado en URL).
- perfil
- consulta · cadena - Solo este ID de perfil (coincidencia exacta).
- desde
- consulta · cadena (fecha y hora) - Solo entradas cuyo
atsea de este timestamp RFC 3339 en adelante (codificado en URL). - estado
- consulta · QueryStatus - Solo entradas en este estado.
- 200
- Las entradas coincidentes, primero las más recientes.
- 400
bad_request:limitno es un número entero,sinceno es RFC 3339,statusdesconocido, o un valor no es una codificación porcentual válida.- 401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
{
"enabled": true,
"total": 2,
"limit": 200,
"queries": [
{
"id": "q-7",
"sessionId": 12,
"kind": "query",
"at": "2026-10-14T15:04:09.120Z",
"user": "dana.analyst",
"profile": "analysts",
"profileName": "Analysts",
"connection": "Northwind",
"server": "sql01.internal",
"database": "Northwind",
"engine": "Microsoft SQL Server",
"sql": "SELECT TOP 100 * FROM Orders",
"sqlTruncated": false,
"status": "completed",
"durationMs": 184,
"error": null
},
{
"id": "q-6",
"sessionId": 12,
"kind": "query",
"at": "2026-10-14T15:03:51.004Z",
"user": "dana.analyst",
"profile": "analysts",
"profileName": "Analysts",
"connection": "Northwind",
"server": "sql01.internal",
"database": "Northwind",
"engine": "Microsoft SQL Server",
"sql": "SELECT * FROM Ordres",
"sqlTruncated": false,
"status": "failed",
"durationMs": 31,
"error": "Invalid object name 'Ordres'."
}
]
}
Ejemplo de respuesta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Vinculación
endpoints de sqlly.app (servidor sqlly.app) para vincular una instalación a una licencia: crea un código, el propietario lo aprueba en su navegador, recoge una vez la clave de la propia instalación y se la pasa al puente con PUT /manage/license.
/api/embedded/links
sqlly.app
sin token
Empieza a vincular una instalación (sqlly.app)
Anónimo. Crea una solicitud de enlace y devuelve un código corto, un secreto que solo tu aplicación conoce, y la URL donde el propietario de la licencia lo aprueba. Muestra el código y abre linkUrl para el propietario, y luego sondea POST /api/embedded/links/token cada pollIntervalSeconds hasta que se apruebe. Los enlaces caducan a los 15 minutos.
Cuerpo de la solicitud (CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- Enlace creado.
- 429
- Se alcanzó el límite de peticiones.
- 503
link_unavailable: no se pudo asignar un código; inténtalo de nuevo.
Ejemplo de respuesta 201
{
"linkId": "eml_Y2h9u0bQ1sXk4tWm8pZr3vLa",
"code": "K7Q-4MX",
"secret": "pW0r7…",
"linkUrl": "https://sqlly.app/embedded/link?code=K7Q-4MX",
"expiresAt": "2026-10-14T15:17:11Z",
"pollIntervalSeconds": 3
}
/api/embedded/links/token
sqlly.app
sin token
Sondear la clave vinculada (sqlly.app)
Anónimo; el secreto del enlace es la credencial. Mientras el propietario no haya decidido, responde 202 pending. Una vez aprobado, genera la clave de licencia propia de esta instalación y la devuelve una sola vez (el enlace se consume). Entrega la clave directamente al puente con PUT /manage/license; no la almacenes tú mismo.
Cuerpo de la solicitud (LinkTokenRequest)
- 200
- Aprobado: la clave, una vez.
- 202
- Todavía a la espera del propietario.
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expiredolicense_revoked: este enlace nunca puede completarse. Inicia uno nuevo.- 429
- Se alcanzó el límite de peticiones.
/api/embedded/public-key
sqlly.app
sin token
Clave pública para la firma de licencias (sqlly.app)
La clave pública PEM con la que sqlly.app firma las concesiones de licencia, para que un operador pueda compararla con la clave compilada en el puente.
- 200
- Texto PEM.
- 503
signing_not_configured.
Esquemas
Los objetos anteriores, tal como están definidos en swagger.json. Una ? después de un tipo significa que puede ser null.
Error
Cada respuesta de error. error es un código de máquina estable; message es una frase que puedes mostrar a un administrador.
| Campo | Tipo | Descripción |
|---|---|---|
error * |
string |
|
message * |
string |
|
problems |
string[] |
Presente para invalid_profile: cada problema que el analizador de credenciales encontró. |
LicenseState
ok y grace sirve consultas; cualquier otro estado rechaza el trabajo con un mensaje que SQLly muestra a sus usuarios.
Uno de: ok grace stale not_admitted expired revoked domain_mismatch unlicensed
StatusReport
| Campo | Tipo | Descripción |
|---|---|---|
version |
string |
Versión del puente. |
instanceId |
string |
Id de este proceso de puente tal como lo ve sqlly.app. |
mode |
connected | offline |
|
license |
LicenseReport |
|
seatsUsed |
integer |
Asientos en uso en cada puente de la licencia. |
activeSessions |
integer |
Sesiones SQLly abiertas en este puente. |
proxyUrl |
string |
La URL de WebSocket que usan los navegadores (--public-url). |
allowLocalhostOrigins |
boolean |
|
storeUrl |
string |
|
allowFileEngines |
boolean |
Si los perfiles pueden contener motores basados en archivos (--allow-file-engines). |
LicenseReport
Los permisos provienen de la concesión firmada, nunca de datos sin firmar.
| Campo | Tipo | Descripción |
|---|---|---|
state |
LicenseState |
|
source |
flag | file | linked | none |
flag: --license-key; file: --license-file; linked: almacenado por PUT /manage/license; none: sin licencia. |
licenseId |
string? |
|
plan |
string? |
Id del plan, o custom para una licencia emitida con sus propios términos. |
planName |
string? |
|
status |
string? |
estado de sqlly.app en la última comprobación: active, grace, expired, revoked, domain_mismatch. |
seats |
integer |
Usuarios concurrentes que permite la licencia. |
sessionsPerSeat |
integer |
Pestañas de SQLly abiertas que puede tener un solo usuario. |
instances |
integer |
Puentes que pueden estar activos a la vez (licencias conectadas; 0 sin conexión). |
domain |
string? |
El dominio vinculado; los navegadores deben venir de él o de un subdominio. |
periodEnd |
string? |
Fin del período pagado (ISO 8601). |
graceEnd |
string? |
Se establece durante el periodo de gracia: cuando el puente deja de servir. |
daysRemaining |
integer? |
Días completos hasta que el puente deje de funcionar. |
lastCheckinAt |
string (date-time)? |
|
staleAt |
string (date-time)? |
Cuándo se vuelve obsoleto el puente si no hay ninguna verificación con éxito (última concesión válida + 40 minutos). |
licenseFile |
string? |
Sin conexión: el archivo de licencia en uso. |
message |
string? |
La frase que ven los usuarios cuando algo va mal (también las cuentas regresivas de gracia). |
fromCache |
boolean |
Verdadero cuando el puente se inició con la concesión en caché porque sqlly.app no estaba accesible. |
features |
string[] |
LinkLicenseRequest
| Campo | Tipo | Descripción |
|---|---|---|
licenseKey * |
string |
Una clave que empieza por sqe_. |
EngineInfo
| Campo | Tipo | Descripción |
|---|---|---|
id |
string |
La engine valor para un documento de credencial. |
name |
string |
|
defaultPort |
integer |
|
fileBased |
boolean |
server es una ruta de archivo y no se requiere iniciar sesión. |
authentication |
string[] |
Aceptado authentication.type valores. |
ProfileSummary
| Campo | Tipo | Descripción |
|---|---|---|
id |
string |
|
name |
string |
|
connections |
integer |
Número de conexiones en el documento. |
updatedAt |
string (date-time) |
StoredProfile
| Campo | Tipo | Descripción |
|---|---|---|
id |
string |
|
name |
string |
|
credentials |
CredentialDocument |
|
updatedAt |
string (date-time) |
PutProfileRequest
| Campo | Tipo | Descripción |
|---|---|---|
name * |
string |
Nombre para mostrar, el que verán los usuarios en SQLly. |
credentials * |
CredentialDocument |
CredentialDocument
Un documento de credenciales de SQLly (el mismo formato que Archivo → Importar Conexiones de SQLly). Las claves desconocidas se tratan como errores, así que los errores tipográficos se notifican en vez de pasarse por alto. Referencia completa: sqlly.app/docs (Formato de archivo de credenciales).
| Campo | Tipo | Descripción |
|---|---|---|
format * |
sqlly-credentials |
|
version * |
1 |
|
clients |
Label[] |
|
projects |
Label[] |
|
environments |
Label[] |
|
sql_auth_accounts |
SharedLogin[] |
|
tunnel_profiles |
object[] |
|
connections |
Connection[] |
Etiqueta
| Campo | Tipo | Descripción |
|---|---|---|
name * |
string |
|
color |
string |
#RGB, #RRGGBB o #RRGGBBAA. |
image |
string |
Icono como URI de datos o base64 sin formato (PNG, JPEG, GIF, WebP, BMP, ICO, SVG; hasta 1 MB). |
safety |
object |
Solo cambian los indicadores que enumeres. |
SharedLogin
| Campo | Tipo | Descripción |
|---|---|---|
name * |
string |
|
username * |
string |
|
password |
string |
Conexión
| Campo | Tipo | Descripción |
|---|---|---|
name * |
string |
|
engine * |
string |
Un id de GET /manage/engines. |
server * |
string |
Host, IP, host\instance o una ruta de archivo para SQLite/DuckDB. |
port |
integer |
|
database |
string |
|
environment |
string |
local, dev, test, staging, production o sin establecer. |
client |
string |
Un nombre de etiqueta de cliente. |
project |
string |
Un nombre de etiqueta de proyecto. |
authentication |
Authentication |
|
tls |
object |
|
timeout_seconds |
integer |
|
statement_timeout_seconds |
integer |
|
application_name |
string |
|
safety |
object |
|
favorite |
boolean |
|
startup_sql |
string |
|
tunnel_profile |
string |
|
transport |
object |
Proxy integrado, con saltos ssh y kube. |
masking |
object |
{ include: [...], exclude: [...] } reglas de enmascaramiento de columnas. |
Autenticación
| Campo | Tipo | Descripción |
|---|---|---|
type * |
sql-login | integrated | entra-browser | entra-device-code | aws-rds-iam | gcp-cloud-sql-iam | auth-token | none |
|
username |
string |
|
password |
string |
|
account |
string |
Nombre de un inicio de sesión compartido en sql_auth_accounts. |
region |
string |
|
profile |
string |
|
token |
string |
MintTokenRequest
| Campo | Tipo | Descripción |
|---|---|---|
user * |
string |
Tu ID estable para el usuario (sin espacios en blanco). Los asientos se cuentan por cada usuario distinto. |
profile * |
string |
Un ID de perfil. |
ttlSeconds |
integer |
Duración del token; por defecto es --token-ttl-seconds (600) y se limita al rango de 10 s a 24 h. |
open |
LaunchTab | LaunchTab[] |
Contexto de lanzamiento: una pestaña de consulta, o hasta 8, que SQLly abre al iniciar la sesión. La primera sesión que el token admite las recibe; las recargas y las sesiones posteriores no. Se valida contra el perfil en el momento de crearlo (400 invalid_open). Nada se ejecuta hasta que el usuario presiona Ejecutar. Guía: sqlly.app/docs/embedded/launch-context |
LaunchTab
Una pestaña de consulta de un lanzamiento. Necesita un script, un connection, o ambos.
| Campo | Tipo | Descripción |
|---|---|---|
connection |
string |
Una conexión del perfil del token, por nombre (sin distinguir mayúsculas de minúsculas, debe ser único) o por id. Es opcional cuando el perfil tiene una sola conexión; si hay varias y no se indica ninguna, la pestaña se abre sin vincular. |
database |
string |
Base de datos a la que cambiar en vez de la predeterminada de la conexión. |
title |
string |
El título de la pestaña. |
script |
string |
El SQL a cargar, tal cual (máximo 256 KiB; CRLF se convierte a LF). |
parameters |
object |
Valores para los @name parámetros, indexados por nombre (con o sin @). El tipo de un valor sin comillas se infiere (número entero → int, otro número → decimal, booleano → bool, cadena → text, nulo → empty); usa { type, value } para elegir. Los parámetros que el script no declara obtienen una línea -- sqlly param: línea; los valores aparecen en la franja de parámetros de SQLly y nunca los incrusta tu aplicación. |
cursor |
LaunchCursor |
LaunchParameterValue
| Campo | Tipo | Descripción |
|---|---|---|
type |
text | int | decimal | bool | date | datetime | time | uuid | json | binary |
|
value |
string | number | boolean |
LaunchCursor
Posición del cursor en script, empezando en 1; la columna cuenta caracteres y puede apuntar uno más allá del final de la línea.
| Campo | Tipo | Descripción |
|---|---|---|
line |
integer |
|
column |
integer |
MintedToken
| Campo | Tipo | Descripción |
|---|---|---|
token |
string |
|
expiresAt |
string (date-time) |
|
proxyUrl |
string |
|
user |
string |
|
profile |
string |
|
seatsUsed |
integer |
Asientos en uso, incluido este usuario. |
seats |
integer |
|
openTabs |
integer |
Cuántas pestañas abrirá la sesión (0 sin contexto de inicio). |
SeatsReport
| Campo | Tipo | Descripción |
|---|---|---|
seats |
integer |
|
seatsUsed |
integer |
|
users |
UserSeat[] |
UserSeat
| Campo | Tipo | Descripción |
|---|---|---|
user |
string |
|
activeSessions |
integer |
|
tokens |
integer |
Tokens de lanzamiento sin caducar. |
since |
string (date-time) |
SolicitudDePruebaDeConexión
| Campo | Tipo | Descripción |
|---|---|---|
credentials * |
CredentialDocument |
ResultadoDePrueba
| Campo | Tipo | Descripción |
|---|---|---|
ok |
boolean |
|
elapsedMs |
integer |
|
message |
string |
El mensaje del propio motor, sea de éxito o de fallo. |
QueryStatus
running hasta que el motor responda; entonces completed, failed (ver error) o cancelled (por el usuario, o session closed).
Uno de: running completed failed cancelled
QueryEntry
Una solicitud auditada.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string |
El id de la solicitud del motor, único dentro de su sesión. |
sessionId |
integer |
El id del puente para la sesión del navegador. |
kind |
query | row-edit |
|
at |
string (date-time) |
Cuándo llegó la solicitud al puente. |
user |
string |
El id de usuario del token de lanzamiento. |
profile |
string |
El id de perfil del token de lanzamiento. |
profileName |
string |
|
connection |
string |
El nombre de la conexión en el perfil. |
server |
string |
|
database |
string? |
La base de datos del perfil si este fija una; si no, la base de datos que indique la solicitud. |
engine |
string |
El nombre para mostrar del motor. |
sql |
string |
El texto SQL, o row edit: <op> para una edición de fila. Recortado a 64 KiB. |
sqlTruncated |
boolean |
|
status |
QueryStatus |
|
durationMs |
integer? |
Nulo mientras se ejecuta. |
error |
string? |
El error del motor para failed; session closed para una solicitud interrumpida por el fin de su sesión. |
QueryListing
| Campo | Tipo | Descripción |
|---|---|---|
enabled |
boolean |
Falso cuando el puente se ejecuta con --query-log false; entonces queries siempre está vacío. |
queries |
QueryEntry[] |
Los más recientes primero. |
total |
integer |
Entradas que coinciden con los filtros antes de limit se aplicó. |
limit |
integer |
El tamaño de página aplicado (1-1000). |
CreateLinkRequest
| Campo | Tipo | Descripción |
|---|---|---|
name |
string |
Mostrado al propietario en la página de aprobación y en su página Embedded. |
hostname |
string |
|
appVersion |
string |
CreateLinkResponse
| Campo | Tipo | Descripción |
|---|---|---|
linkId |
string |
|
code |
string |
Muestra esto al propietario para que pueda comprobar que coincide. |
secret |
string |
Mantener en el servidor; recopila la clave. |
linkUrl |
string |
Abre esto para que el propietario lo apruebe. |
expiresAt |
string (date-time) |
|
pollIntervalSeconds |
integer |
LinkTokenRequest
| Campo | Tipo | Descripción |
|---|---|---|
linkId * |
string |
|
secret * |
string |
LinkPending
| Campo | Tipo | Descripción |
|---|---|---|
status |
pending |
|
expiresAt |
string (date-time) |
LinkApproved
| Campo | Tipo | Descripción |
|---|---|---|
status |
approved |
|
licenseKey |
string |
Devuelto exactamente una vez. Pásalo a PUT /manage/license. |
keyId |
string |
|
licenseId |
string |
|
plan |
string |
Id del plan, o custom. |
planName |
string |
|
accountEmail |
string |
* obligatorio