Hubfly spaceDocs
Console

Managed Databases API · Dashboard

Connect & credentials

Read connection details, reveal or rotate the admin password, download the CA certificate, and open a short-lived shell session.

Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.

Database instances live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the database instance ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the database permissions must hold that exact permission.

How to use these endpoints

  1. Read the connection details for the host, port, database and user. The response never includes the password.
  2. Reveal the admin password only when you need it; every reveal is recorded in the audit log. Rotating it returns the new password once and updates apps bound with the admin user.
  3. Connect with TLS. Download the instance CA certificate to verify the server (sslmode=verify-full for PostgreSQL).

Reveal the admin connection string

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/credentials/reveal" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.

Endpoint reference

Dashboard endpoints (5)

These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.

Open interactive API explorer
GETDownload the TLS certificateDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/certificate

Returns the database's TLS certificate as PEM with its SHA-256 fingerprint, expiry and a suggested file name. Use it to verify the server with sslmode=verify-full or the MySQL equivalent.

  • Requires database:read.
  • Returns 404 MANAGED_CERTIFICATE_UNAVAILABLE until the instance is ready.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "pem": {
              "type": "string"
            },
            "fingerprintSha256": {
              "type": "string",
              "nullable": true
            },
            "expiresAt": {
              "type": "string",
              "description": "Date string",
              "nullable": true
            },
            "fileName": {
              "type": "string"
            }
          },
          "required": [
            "pem",
            "fingerprintSha256",
            "expiresAt",
            "fileName"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "pem": "string",
        "fingerprintSha256": "string",
        "expiresAt": "string",
        "fileName": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETRead connection detailsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/connection

Returns how to connect to the database: engine, host, port, default database, admin username, whether public access is on and whether the endpoint is ready, the TLS mode and, for SQLite, the libsql:// and https:// URLs. The password or token is not included.

  • Requires database:read.
  • secretKind tells you whether to reveal a password or create an access token.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "engine": {
              "type": "string",
              "enum": [
                "postgresql",
                "mysql",
                "libsql"
              ]
            },
            "host": {
              "type": "string"
            },
            "port": {
              "type": "number",
              "nullable": true
            },
            "database": {
              "type": "string",
              "nullable": true
            },
            "username": {
              "type": "string",
              "nullable": true
            },
            "publicAccess": {
              "type": "boolean"
            },
            "ready": {
              "type": "boolean"
            },
            "tls": {
              "type": "object",
              "properties": {
                "required": {
                  "type": "boolean"
                },
                "verification": {
                  "type": "string",
                  "enum": [
                    "self_signed",
                    "public_ca"
                  ]
                },
                "certificateAvailable": {
                  "type": "boolean"
                }
              },
              "required": [
                "required",
                "verification",
                "certificateAvailable"
              ],
              "additionalProperties": false
            },
            "libsqlUrl": {
              "type": "string",
              "nullable": true
            },
            "httpUrl": {
              "type": "string",
              "nullable": true
            },
            "secretKind": {
              "type": "string",
              "enum": [
                "password",
                "token"
              ]
            },
            "credentialsRotatedAt": {
              "type": "string",
              "description": "Date string",
              "nullable": true
            }
          },
          "required": [
            "engine",
            "host",
            "port",
            "database",
            "username",
            "publicAccess",
            "ready",
            "tls",
            "libsqlUrl",
            "httpUrl",
            "secretKind",
            "credentialsRotatedAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "engine": "postgresql",
        "host": "string",
        "port": 0,
        "database": "string",
        "username": "string",
        "publicAccess": true,
        "ready": true,
        "tls": {
          "required": true,
          "verification": "self_signed",
          "certificateAvailable": true
        },
        "libsqlUrl": "string",
        "httpUrl": "string",
        "secretKind": "password",
        "credentialsRotatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTReveal the admin passwordDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/credentials/reveal

Returns the admin username and current password of a PostgreSQL or MySQL database. Every reveal is recorded in the audit log.

  • Requires database:admin.
  • The response contains a secret and is sent with cache-control: no-store.
  • SQLite instances use access tokens instead and return 409 MANAGED_USE_TOKENS.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "kind": {
              "const": "password",
              "type": "string"
            },
            "username": {
              "type": "string"
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "username",
            "value"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "kind": "string",
        "username": "string",
        "value": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRotate admin credentialsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/credentials/rotate

For PostgreSQL and MySQL, sets a new admin password, returns it and rewrites the connection URL in connected apps that use the admin user. For SQLite, replaces the signing key, which revokes every access token, and gives connected apps a new token.

  • Requires database:admin.
  • The new password is returned once in this response, sent with cache-control: no-store.
  • The database must be running.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "const": "password",
                  "type": "string"
                },
                "username": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "kind",
                "username",
                "value"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "const": "signing_key",
                  "type": "string"
                },
                "revokedTokens": {
                  "type": "number"
                },
                "appsReconnected": {
                  "type": "number"
                }
              },
              "required": [
                "kind",
                "revokedTokens",
                "appsReconnected"
              ],
              "additionalProperties": false
            }
          ]
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": null,
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTOpen a database shellDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/shell/session

Creates a short-lived browser terminal session that opens psql or the mysql client on the database, never a system shell. Returns the session ID, a connect URL and token, and the expiry.

  • Requires database:query.
  • Available for PostgreSQL and MySQL (409 MANAGED_FEATURE_UNSUPPORTED otherwise); the instance must be running (409 MANAGED_INSTANCE_NOT_RUNNING).
  • The connect token is a secret; the response is sent with cache-control: no-store.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "sessionId": {
              "type": "string"
            },
            "connectToken": {
              "type": "string"
            },
            "connectUrl": {
              "type": "string"
            },
            "shell": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            }
          },
          "required": [
            "sessionId",
            "connectToken",
            "connectUrl",
            "shell",
            "expiresAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "sessionId": "string",
        "connectToken": "string",
        "connectUrl": "string",
        "shell": "string",
        "expiresAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top