Référence de l’API
Chaque point de terminaison de l'API de gestion du pont SQLly Embedded, généré à partir de son document OpenAPI (swagger.json), plus les points de terminaison de liaison sqlly.app.
Le pont SQLly en mode embarqué expose cette API sur son écouteur de gestion (--manage-bind, par défaut 127.0.0.1:8445). Votre application web l'appelle depuis son côté serveur pour stocker des profils de connexion, tester des connexions, créer des jetons de lancement pour les utilisateurs connectés, suivre les postes attribués et lire ou modifier l'état de la licence.
Chaque /manage/... appel nécessite Authorization: Bearer <manage token> (le --manage-token, au moins 16 caractères). Les corps sont en JSON en entrée et sortie, au maximum 8 Mo (refusé avec 413 too_large dès que la limite est dépassée). Les segments de chemin et les valeurs de la chaîne de requête sont décodés en pourcentage ; une séquence d'échappement invalide est 400 bad_request. Les erreurs sont toujours { "error": "<code>", "message": "<sentence>" }, ainsi que problems lorsqu'un document d'identification est invalide. L'API n'envoie aucun en-tête CORS : gardez-la sur la boucle locale ou un réseau privé et ne l'exposez jamais aux navigateurs, car les profils contiennent les mots de passe des bases de données.
Le Linking les opérations ne sont pas sur le pont : ce sont les points de terminaison publics de sqlly.app qu'une application d'administration utilise pour lier une installation à une licence sans copier de clé. Leur serveur est sqlly.app.
Guide : sqlly.app/docs/embedded
Conventions
- Authentification :
Authorization: Bearer <manage token>à chaque fois/manage/…appel. Un jeton manquant ou incorrect est401 unauthorized./healthzet les points de liaison de sqlly.app n'en nécessitent aucun. - Erreurs sont
{ "error": "<code>", "message": "<sentence>" }. Branchez surerror; affichezmessage. Les documents d'identifiants invalides ajoutentproblems, une chaîne par erreur. - Corps sont du JSON, au maximum 8 Mo. La limite est appliquée pendant la réception du corps : le pont répond
413 too_largedès qu'il est transmis, sans jamais rien mettre de plus en mémoire tampon. Un corps qui met plus de 30 secondes à arriver est408 timeout. Tout ce qui ne peut pas être analysé est400 bad_json, et une route inconnue est404 not_found. - Segments de chemin et valeurs de requête sont décodés à partir de l'encodage pourcentage, donc encodez en URL les identifiants d'utilisateur et les horodatages (
DELETE /manage/seats/a%2Fblibère l'utilisateura/b). Une séquence d'échappement invalide ou un résultat qui n'est pas en UTF-8 est400 bad_request. - Noms de champs sont en camelCase dans les charges utiles de l'API. Dans un document d'identifiants, ils suivent le format des identifiants (
sql_auth_accounts,trust_server_certificate).
Points de terminaison
- 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
Santé
Vérification de disponibilité, pas de jeton nécessaire.
/healthz
pas de jeton
Sonde de disponibilité
Répond dès que l'écouteur de gestion est actif. Aucun jeton n'est nécessaire ; utilisez-le à partir des scripts de démarrage et des contrôles de santé des services.
- 200
- L’API de gestion est en écoute.
Exemple de réponse 200
{
"ok": true
}
Licence
La licence sous laquelle le pont fonctionne : état, enregistrement, liaison et dissociation.
/manage/status
Statut du pont et de la licence
Tout ce dont un écran d'administration a besoin : l'état de la licence et son origine, les droits que porte l'attribution signée, les sièges en cours d'utilisation, les sessions ouvertes et l'URL du proxy utilisée par les navigateurs.
- 200
- Statut actuel.
- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 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
}
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license/checkin
Contactez sqlly.app maintenant
Licences connectées et liées : effectue immédiatement un contrôle auprès du serveur au lieu d'attendre la boucle de 20 minutes. Licences hors ligne : relit le fichier de licence et ne touche jamais au réseau. Dans tous les cas, la réponse est le statut après la tentative ; un échec laisse l'état inchangé.
- 200
- Statut après l'enregistrement.
- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 409
not_linked: le pont est sans licence, il n'y a rien à signaler au serveur.- 422
license_file_invalid(hors ligne) : le fichier est manquant, endommagé ou signé pour une autre clé.- 502
store_unreachableougrant_invalid: sqlly.app n'a pas pu être atteint, ou sa réponse n'a pas été vérifiée.
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Exemple de réponse 409
{
"error": "not_linked",
"message": "this bridge is not linked to a license yet"
}
/manage/license
Installer une clé de licence liée
Donne à un pont démarré sans --license-key / --license-file sa clé à l'exécution (normalement la clé que votre application d'admin vient de récupérer auprès de sqlly.app via le flux de liaison). Le pont s'enregistre d'abord avec elle et la stocke (<state-dir>/license-key, mode 0600) seulement si sqlly.app répond avec une autorisation vérifiée ; à partir de ce moment-là, il fonctionne comme un pont connecté, et la clé est réutilisée après les redémarrages. Rien ne change en cas d'échec : la clé utilisée continue de servir jusqu'à ce que la nouvelle soit vérifiée. Remplacer une clé liée par une autre d'une autre licence libère l'emplacement d'instance de l'ancienne licence après que la nouvelle clé soit vérifiée ; une clé régénérée de la même licence réutilise la ligne d'instance du magasin.
Corps de la requête (LinkLicenseRequest)
{
"licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
- 200
- Lié. Le statut affiche maintenant
license.source: linked. - 400
invalid_license_key: clé vide, mal formée, inconnue ou révoquée.- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 409
license_from_flag: le pont a été démarré avec--license-keyou--license-file, donc sa licence n'est pas gérée via cette API.- 502
store_unreachable: sqlly.app n'a pas pu être atteint ou sa réponse n'a pas été vérifiée.
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license
Dissocier cette installation
Libère l'emplacement d'instance de ce pont, révoque sa clé sur sqlly.app (dans la mesure du possible), supprime la clé stockée, ferme toutes les sessions ouvertes et renvoie le pont à unlicensed.
- 204
- Dissocié.
- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 404
not_linked: aucune clé liée n'est enregistrée.- 409
license_from_flag: le pont a été démarré avec--license-keyou--license-file, donc sa licence n'est pas gérée via cette API.
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Moteurs
Les moteurs de base de données acceptés par le format d'identifiants, donc votre interface utilisateur ne code jamais en dur la liste.
/manage/engines
Moteurs acceptés par le format d'identifiants
Chaque moteur de base de données pris en charge par SQLly, avec le engine id à écrire dans un document d'identification, son port par défaut, si server est un chemin de fichier, et les authentication.type valeurs qu'il accepte.
- 200
- Les moteurs.
- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 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"
]
}
]
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Profils
Un profil est un document d'identifiants SQLly nommé : les connexions (et étiquettes) que voit un groupe d'utilisateurs. Le pont est le magasin de référence ; les secrets n'atteignent jamais le navigateur.
/manage/profiles
Lister les profils
Chaque profil stocké sans ses identifiants.
- 200
- Les profils.
- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
[
{
"id": "analysts",
"name": "Analysts",
"connections": 2,
"updatedAt": "2026-10-14T15:02:11Z"
}
]
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Lire un profil
Le profil avec son document d'identification complet, secrets inclus : l'appelant est votre application serveur de confiance.
- id
- chemin · chaîne correspondant à ^[A-Za-z0-9_-]{1,64}$ · obligatoire - Votre identifiant pour le profil.
- 200
- Le profil.
- 400
invalid_profile_id: les identifiants sont de 1 à 64 deA-Z a-z 0-9 _ -.- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 404
unknown_profile: aucun profil n'a cet identifiant.
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Exemple de réponse 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
Créer ou remplacer un profil
Stocke le profil sous id (créer ou remplacer). Le document d'identification est entièrement validé avant toute écriture : chaque problème trouvé par le parseur est renvoyé dans problems, et un document invalide ne change rien. Un document contenant un moteur basé sur un fichier (SQLite, DuckDB) est refusé de la même manière sauf si le pont fonctionne avec --allow-file-engines true, parce qu'une telle connexion offre à ses utilisateurs un accès aux fichiers sur l'hôte du pont. Les sessions déjà ouvertes conservent le catalogue avec lequel elles ont commencé ; les modifications s'appliquent au prochain lancement.
- id
- chemin · chaîne correspondant à ^[A-Za-z0-9_-]{1,64}$ · obligatoire - Votre identifiant pour le profil.
Corps de la requête (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
- Enregistré.
- 400
invalid_profile(avecproblems: problèmes de l'analyseur, ou chaque moteur basé sur des fichiers pendant--allow-file-enginesest désactivé), ouinvalid_profile_id.- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 500
storage: le répertoire d'état n'a pas pu être écrit.
Exemple de réponse 400
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Supprimer un profil
Supprime le profil. Les sessions ouvertes conservent le catalogue avec lequel elles ont démarré ; les nouveaux jetons de lancement pour ce profil sont refusés avec unknown_profile.
- id
- chemin · chaîne correspondant à ^[A-Za-z0-9_-]{1,64}$ · obligatoire - Votre identifiant pour le profil.
- 204
- Supprimé.
- 400
invalid_profile_id: les identifiants sont de 1 à 64 deA-Z a-z 0-9 _ -.- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 404
unknown_profile: aucun profil n'a cet identifiant.
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Exemple de réponse 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
Lancer
Les jetons de lancement ouvrent SQLly pour un utilisateur avec un profil. Un siège correspond à un utilisateur simultané.
/manage/tokens
Créer un jeton de lancement
Crée un jeton de courte durée qui ouvre SQLly pour user avec profile, éventuellement directement dans les onglets de requêtes (open, le contexte de lancement). Mettez le proxyUrl et token renvoyé dans la page qui charge SQLly (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). Le jeton peut être réutilisé jusqu'à ce qu'il expire (rechargement de la page), et le profil est enregistré au moment de la création.
Un utilisateur occupe un siège tant qu'il a une session ouverte ou un jeton non expiré. Générer un jeton pour un utilisateur qui occupe déjà un siège n'échoue jamais à cause du nombre de sièges ; en générer un pour un nouvel utilisateur échoue avec seat_limit lorsque toutes les places de la licence sont utilisées, en comptant les utilisateurs sur chacun des ponts de la licence.
Corps de la requête (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
- Le jeton.
- 400
invalid_user(vide ou contient des espaces, au maximum 128 caractères),invalid_profile(le profil stocké n’est plus valide, ou contient un moteur basé sur un fichier tandis que--allow-file-enginesest désactivé), ouinvalid_open(le contexte de lancement mentionne une connexion inconnue, un champ ou type inconnu, un mauvais nom ou valeur de paramètre, un curseur hors limites, ou dépasse une limite;problemsliste chaque erreur avec son chemin, par exempleopen[1].cursor: …).- 401
unauthorized: le jeton de gestion est manquant ou incorrect.- 404
unknown_profile: aucun profil n'a cet identifiant.- 409
seat_limit: chaque siège est utilisé. Libérez-en un (DELETE /manage/seats/{user}) ou achetez un plan plus grand.- 503
license_not_ok: la licence n’est pasokougrace(périmé, expiré, révoqué, non admis, domaine non correspondant ou sans licence). Le message indique lequel.
Exemple de réponse 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
}
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats
Sièges utilisés
Utilisateurs occupant un siège sur ce pont, avec leurs sessions ouvertes et leurs jetons actifs. seatsUsed compte également les utilisateurs signalés par sqlly.app sur d’autres ponts de la même licence.
- 200
- Utilisation des sièges.
- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 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"
}
]
}
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
Libérer le siège d'un utilisateur
Révoque les jetons de l'utilisateur et ferme ses sessions, libérant ainsi immédiatement le siège. Appelez cette fonction lorsqu'un utilisateur se déconnecte de votre application ou perd l'accès. Libérer un utilisateur qui ne détient aucun siège n'est pas une erreur. Le segment de chemin est décodé (décodage pourcent, comme dans une URL) : a%2Fb libère l'utilisateur a/b.
- utilisateur
- chemin · chaîne · obligatoire - L'identifiant utilisateur pour lequel vous avez émis des jetons (codé en URL).
- 204
- Publié.
- 400
bad_request: le segment n'est pas un encodage de pourcentage valide.- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Connexions
Vérifiez qu'une connexion fonctionne avant que quiconque ne l'utilise.
/manage/test-connection
Tester une connexion
Exécute un moteur éphémère sur un document d'identifiants ne contenant qu'une seule connexion et exécute une requête triviale. Les échecs de connexion sont signalés comme ok: false avec le message du moteur lui-même (HTTP 200) ; seul un document inutilisable est une erreur HTTP.
Corps de la requête (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
- Le résultat, succès ou échec.
- 400
invalid_profile: le document est invalide, ne contient pas exactement une connexion, ou contient un moteur basé sur un fichier alors que--allow-file-enginesest désactivé (voirproblems).- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
{
"ok": true,
"elapsedMs": 212,
"message": "Connected: SQL Server 17.0"
}
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Audit
La piste d'audit des requêtes : chaque requête et modification de ligne qu'une session a exécutée, qui l'a exécutée, contre quelle connexion, et comment cela s'est terminé. Conservé en mémoire et dans <state-dir>/queries.jsonl (texte SQL inclus) à moins que le pont ne fonctionne avec --query-log false.
/manage/queries
Piste d'audit des requêtes
Chaque requête et modification de ligne que les sessions du pont ont exécutée, la plus récente en premier : l'utilisateur et le profil du jeton de lancement, la connexion qu'il a nommée (nom, serveur, moteur, base de données), le texte SQL (limité à 64 KiB, voir sqlTruncated), quand il a commencé, son statut et sa durée, et l'erreur du moteur lorsqu'il a échoué. Les requêtes encore en cours sont listées avec leur statut running; une requête refusée parce que la licence n'était pas en règle est failed avec le message de licence ; tout ce qui tournait au moment où la session s'est fermée est cancelled avec l'erreur session closed.
Le pont conserve les entrées les plus récentes --query-log-max-entries (20 000 par défaut) en mémoire et dans <state-dir>/queries.jsonl, donc la trace survit à un redémarrage. Avec --query-log false rien n'est enregistré et la réponse est { "enabled": false, "queries": [] }.
- limite
- requête · entier - Entrées à renvoyer, plafonnées à 1-1000.
- utilisateur
- requête · chaîne - Uniquement cet identifiant d'utilisateur (correspondance exacte, encodé pour l'URL).
- profil
- requête · chaîne - Uniquement cet identifiant de profil (correspondance exacte).
- depuis
- requête · chaîne (date-heure) - Uniquement les entrées dont
atest à ou après ce timestamp RFC 3339 (encodé dans l'URL). - statut
- requête · QueryStatus - Uniquement les entrées ayant ce statut.
- 200
- Les entrées correspondantes, les plus récentes d'abord.
- 400
bad_request:limitn'est pas un nombre entier,sincen'est pas RFC 3339,statusest inconnu, ou une valeur n'est pas un encodage de pourcentage valide.- 401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 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'."
}
]
}
Exemple de réponse 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Liaison
points de terminaison sqlly.app (serveur sqlly.app) pour lier une installation à une licence : créez un code, le propriétaire l'approuve dans son navigateur, récupérez la clé de l'installation une seule fois, puis transmettez-la au pont avec PUT /manage/license.
/api/embedded/links
sqlly.app
pas de jeton
Commencez à lier une installation (sqlly.app)
Anonyme. Crée une demande de lien et renvoie un code court, un secret que seule votre application connaît, et l'URL où le propriétaire de la licence l'approuve. Affichez le code et ouvrez linkUrl pour le propriétaire, puis interrogez POST /api/embedded/links/token chaque pollIntervalSeconds jusqu'à ce qu'il soit approuvé. Les liens expirent après 15 minutes.
Corps de la requête (CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- Lien créé.
- 429
- Limite de débit atteinte.
- 503
link_unavailable: aucun code n'a pu être attribué ; réessayez.
Exemple de réponse 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
pas de jeton
Récupérer la clé liée (sqlly.app)
Anonyme ; le secret du lien est l'identifiant. Tant que le propriétaire n'a pas décidé, répond 202 pending. Une fois approuvé, crée la clé de licence propre à cette installation et la renvoie exactement une fois (le lien est à usage unique). Donnez la clé directement au pont avec PUT /manage/license; ne la stockez pas vous-même.
Corps de la requête (LinkTokenRequest)
- 200
- Approuvé : la clé, une fois.
- 202
- Toujours en attente du propriétaire.
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expiredoulicense_revoked: ce lien ne peut jamais aboutir. Commencez-en un nouveau.- 429
- Limite de débit atteinte.
/api/embedded/public-key
sqlly.app
pas de jeton
Clé publique de signature de licence (sqlly.app)
La clé publique PEM que sqlly.app utilise pour signer les licences, afin qu'un opérateur puisse la comparer avec la clé compilée dans le bridge.
- 200
- Texte PEM.
- 503
signing_not_configured.
Schémas
Les objets ci-dessus, tels que définis dans swagger.json. Une ? après un type signifie qu’il peut être null.
Erreur
Chaque réponse d'erreur. error est un code machine stable ; message est une phrase que vous pouvez montrer à un administrateur.
| Champ | Type | Description |
|---|---|---|
error * |
string |
|
message * |
string |
|
problems |
string[] |
Présent pour invalid_profile: chaque problème que l'analyseur d'identifiants a trouvé. |
LicenseState
ok et grace servir les requêtes ; tout autre état refuse de traiter la demande avec un message que SQLly affiche à ses utilisateurs.
Un parmi : ok grace stale not_admitted expired revoked domain_mismatch unlicensed
StatusReport
| Champ | Type | Description |
|---|---|---|
version |
string |
Version du pont. |
instanceId |
string |
L'identifiant de ce processus de pont, tel que sqlly.app le voit. |
mode |
connected | offline |
|
license |
LicenseReport |
|
seatsUsed |
integer |
Sièges utilisés sur tous les ponts de la licence. |
activeSessions |
integer |
Sessions SQLly ouvertes sur ce pont. |
proxyUrl |
string |
L'URL WebSocket utilisée par les navigateurs (--public-url). |
allowLocalhostOrigins |
boolean |
|
storeUrl |
string |
|
allowFileEngines |
boolean |
Si les profils peuvent contenir des moteurs basés sur des fichiers (--allow-file-engines). |
Rapport de licence
Les droits viennent de l'octroi signé, jamais de données non signées.
| Champ | Type | Description |
|---|---|---|
state |
LicenseState |
|
source |
flag | file | linked | none |
flag: --license-key; file: --license-file; linked: stocké par PUT /manage/license; none: sans licence. |
licenseId |
string? |
|
plan |
string? |
Identifiant du plan, ou custom pour une licence délivrée avec ses propres conditions. |
planName |
string? |
|
status |
string? |
Statut de sqlly.app depuis le dernier enregistrement : actif, période de grâce, expiré, révoqué, incompatibilité de domaine. |
seats |
integer |
Utilisateurs concurrents autorisés par la licence. |
sessionsPerSeat |
integer |
Onglets SQLly ouverts qu’un même utilisateur peut avoir. |
instances |
integer |
Ponts pouvant fonctionner simultanément (licences connectées ; 0 hors ligne). |
domain |
string? |
Domaine lié ; les navigateurs doivent provenir de celui-ci ou d’un sous-domaine. |
periodEnd |
string? |
Fin de la période payante (ISO 8601). |
graceEnd |
string? |
Défini pendant la période de grâce : le moment où le pont cesse de répondre. |
daysRemaining |
integer? |
Nombre de jours entiers avant que le pont ne cesse de servir. |
lastCheckinAt |
string (date-time)? |
|
staleAt |
string (date-time)? |
Quand le pont est considéré comme périmé si aucun check-in ne réussit (dernière autorisation valide + 40 minutes). |
licenseFile |
string? |
Hors ligne : le fichier de licence en cours d’utilisation. |
message |
string? |
La phrase que les utilisateurs voient lorsqu'il y a un problème (y compris les délais de grâce). |
fromCache |
boolean |
Vrai lorsque le pont a démarré avec l’autorisation qu’il avait en cache, parce que sqlly.app était injoignable. |
features |
string[] |
LinkLicenseRequest
| Champ | Type | Description |
|---|---|---|
licenseKey * |
string |
Une clé commençant sqe_. |
EngineInfo
| Champ | Type | Description |
|---|---|---|
id |
string |
Le engine valeur pour un document d'identification. |
name |
string |
|
defaultPort |
integer |
|
fileBased |
boolean |
server est un chemin de fichier et aucune authentification ne s'applique. |
authentication |
string[] |
Accepté authentication.type valeurs. |
ProfileSummary
| Champ | Type | Description |
|---|---|---|
id |
string |
|
name |
string |
|
connections |
integer |
Nombre de connexions dans le document. |
updatedAt |
string (date-time) |
StoredProfile
| Champ | Type | Description |
|---|---|---|
id |
string |
|
name |
string |
|
credentials |
CredentialDocument |
|
updatedAt |
string (date-time) |
PutProfileRequest
| Champ | Type | Description |
|---|---|---|
name * |
string |
Nom d’affichage, visible par les utilisateurs dans SQLly. |
credentials * |
CredentialDocument |
CredentialDocument
Un document d'identifiants SQLly (le même format que Fichier → Importer les connexions de SQLly). Les clés inconnues sont des erreurs, donc les fautes de frappe sont signalées au lieu d'être ignorées. Référence complète : sqlly.app/docs (Format du fichier d'identifiants).
| Champ | Type | Description |
|---|---|---|
format * |
sqlly-credentials |
|
version * |
1 |
|
clients |
Label[] |
|
projects |
Label[] |
|
environments |
Label[] |
|
sql_auth_accounts |
SharedLogin[] |
|
tunnel_profiles |
object[] |
|
connections |
Connection[] |
Étiquette
| Champ | Type | Description |
|---|---|---|
name * |
string |
|
color |
string |
#RGB, #RRGGBB ou #RRGGBBAA. |
image |
string |
Icône sous forme d'URI data: ou de base64 brut (PNG, JPEG, GIF, WebP, BMP, ICO, SVG ; jusqu'à 1 Mo). |
safety |
object |
Seuls les indicateurs que vous listez changent. |
SharedLogin
| Champ | Type | Description |
|---|---|---|
name * |
string |
|
username * |
string |
|
password |
string |
Connexion
| Champ | Type | Description |
|---|---|---|
name * |
string |
|
engine * |
string |
Un identifiant provenant de GET /manage/engines. |
server * |
string |
Hôte, IP, hôte\instance ou un chemin de fichier pour SQLite/DuckDB. |
port |
integer |
|
database |
string |
|
environment |
string |
local, dev, test, staging, production ou non défini. |
client |
string |
Un nom d'étiquette client. |
project |
string |
Un nom d'étiquette de projet. |
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 intégré, sauts SSH et kube. |
masking |
object |
{ include: [...], exclude: [...] } Règles de masquage des colonnes. |
Authentification
| Champ | Type | Description |
|---|---|---|
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 |
Nom d'une connexion partagée dans sql_auth_accounts. |
region |
string |
|
profile |
string |
|
token |
string |
MintTokenRequest
| Champ | Type | Description |
|---|---|---|
user * |
string |
Votre identifiant stable pour l’utilisateur (pas d’espace). Les sièges sont comptés par utilisateur distinct. |
profile * |
string |
Un identifiant de profil. |
ttlSeconds |
integer |
Durée de vie du jeton ; par défaut --token-ttl-seconds (600) et est limitée de 10 s à 24 h. |
open |
LaunchTab | LaunchTab[] |
Contexte de lancement : un onglet de requête, ou jusqu'à 8, que SQLly ouvre au démarrage de la session. La première session admise par le jeton les reçoit ; les rechargements et les sessions suivantes, non. Validé par rapport au profil au moment de l'émission (400 invalid_open). Rien ne s'exécute tant que l'utilisateur n'appuie pas sur Exécuter. Guide : sqlly.app/docs/embedded/launch-context |
Onglet de lancement
Un onglet de requête par lancement. Nécessite un script, un connection, ou les deux.
| Champ | Type | Description |
|---|---|---|
connection |
string |
Une connexion du profil du jeton, par nom (insensible à la casse, doit être unique) ou par identifiant. Facultatif quand le profil n'a qu'une seule connexion ; avec plusieurs et aucune nommée, l'onglet s'ouvre sans liaison. |
database |
string |
Base de données à utiliser au lieu de la valeur par défaut de la connexion. |
title |
string |
Le titre de l'onglet. |
script |
string |
Le SQL à charger, tel quel (au maximum 256 KiB ; CRLF est transformé en LF). |
parameters |
object |
Valeurs pour les @name paramètres, indexés par nom (avec ou sans @). Le type d'une valeur brute est inféré (nombre entier int, autre nombre decimal, booléen bool, chaîne text, null empty) ; utilisez { type, value } pour choisir. Les paramètres que le script ne déclare pas obtiennent une ligne -- sqlly param: ligne ; les valeurs apparaissent dans la bande de paramètres de SQLly et ne sont jamais insérées par votre application. |
cursor |
LaunchCursor |
LaunchParameterValue
| Champ | Type | Description |
|---|---|---|
type |
text | int | decimal | bool | date | datetime | time | uuid | json | binary |
|
value |
string | number | boolean |
LaunchCursor
Position du caret dans script, indexée à partir de 1 ; la colonne compte les caractères et peut se trouver juste après la fin de la ligne.
| Champ | Type | Description |
|---|---|---|
line |
integer |
|
column |
integer |
MintedToken
| Champ | Type | Description |
|---|---|---|
token |
string |
|
expiresAt |
string (date-time) |
|
proxyUrl |
string |
|
user |
string |
|
profile |
string |
|
seatsUsed |
integer |
Sièges utilisés incluant cet utilisateur. |
seats |
integer |
|
openTabs |
integer |
Nombre d'onglets que la session ouvrira (0 sans contexte de lancement). |
SeatsReport
| Champ | Type | Description |
|---|---|---|
seats |
integer |
|
seatsUsed |
integer |
|
users |
UserSeat[] |
UserSeat
| Champ | Type | Description |
|---|---|---|
user |
string |
|
activeSessions |
integer |
|
tokens |
integer |
Jetons de lancement non expirés. |
since |
string (date-time) |
TestConnectionRequest
| Champ | Type | Description |
|---|---|---|
credentials * |
CredentialDocument |
TestOutcome
| Champ | Type | Description |
|---|---|---|
ok |
boolean |
|
elapsedMs |
integer |
|
message |
string |
Le message du moteur lui-même, succès ou échec. |
QueryStatus
running jusqu'à ce que le moteur réponde ; puis completed, failed (voir error) ou cancelled (par l'utilisateur, ou session closed).
Un parmi : running completed failed cancelled
QueryEntry
Une seule requête auditée.
| Champ | Type | Description |
|---|---|---|
id |
string |
L'identifiant de requête du moteur, unique au sein de sa session. |
sessionId |
integer |
L'identifiant du pont pour la session du navigateur. |
kind |
query | row-edit |
|
at |
string (date-time) |
Quand la demande a atteint le pont. |
user |
string |
L'identifiant utilisateur du jeton de lancement. |
profile |
string |
L'identifiant du profil du jeton de lancement. |
profileName |
string |
|
connection |
string |
Le nom de la connexion dans le profil. |
server |
string |
|
database |
string? |
La base de données du profil quand il en épingle une, sinon celle que nomme la requête. |
engine |
string |
Le nom d'affichage du moteur. |
sql |
string |
Le texte SQL, ou row edit: <op> pour une édition de ligne. Limité à 64 KiB. |
sqlTruncated |
boolean |
|
status |
QueryStatus |
|
durationMs |
integer? |
Null pendant l'exécution. |
error |
string? |
L'erreur du moteur pour failed; session closed pour une requête interrompue par la fin de sa session. |
QueryListing
| Champ | Type | Description |
|---|---|---|
enabled |
boolean |
Faux lorsque le pont fonctionne avec --query-log false; puis queries est toujours vide. |
queries |
QueryEntry[] |
Le plus récent d'abord. |
total |
integer |
Entrées correspondant aux filtres avant limit a été appliqué. |
limit |
integer |
La taille de page appliquée (1-1000). |
CreateLinkRequest
| Champ | Type | Description |
|---|---|---|
name |
string |
Affiché au propriétaire sur la page d'approbation et sur sa page Embedded. |
hostname |
string |
|
appVersion |
string |
CreateLinkResponse
| Champ | Type | Description |
|---|---|---|
linkId |
string |
|
code |
string |
Montrez cela au propriétaire afin qu'il puisse vérifier que cela correspond. |
secret |
string |
À conserver côté serveur ; c'est lui qui collecte la clé. |
linkUrl |
string |
Ouvrez cela pour que le propriétaire puisse approuver. |
expiresAt |
string (date-time) |
|
pollIntervalSeconds |
integer |
LinkTokenRequest
| Champ | Type | Description |
|---|---|---|
linkId * |
string |
|
secret * |
string |
LinkPending
| Champ | Type | Description |
|---|---|---|
status |
pending |
|
expiresAt |
string (date-time) |
LinkApproved
| Champ | Type | Description |
|---|---|---|
status |
approved |
|
licenseKey |
string |
Renvoyé exactement une fois. Passez-le à PUT /manage/license. |
keyId |
string |
|
licenseId |
string |
|
plan |
string |
Identifiant du plan, ou custom. |
planName |
string |
|
accountEmail |
string |
* obligatoire