Hubfly spaceDocs
Console

Managed Databases API · Dashboard

Users & tokens

Manage PostgreSQL and MySQL users and logical databases, and SQLite/libSQL access tokens.

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. Create one user per application with the narrowest preset: read_only, read_write or admin, for selected databases or all of them.
  2. The new user's password is returned once, by the create or rotate call. Store it before leaving the response.
  3. SQLite/libSQL instances use access tokens instead of users. A token is shown once, when it is created. Revoking a token replaces the signing key, so every token of the instance stops working and bound apps receive a new one.

Create a read-only user

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/users/create" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"reporting","preset":"read_only","databases":["app"]}'

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 (11)

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

Open interactive API explorer
POSTCreate a databaseDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/databases/create

Creates a logical database on a PostgreSQL or MySQL instance, owned by the admin user unless owner names another user. Optional encoding and collation are passed to the engine.

  • Requires database:admin.
  • name uses up to 63 lowercase letters, numbers and underscores and starts with a letter or underscore (400 MANAGED_INVALID_DATABASE_NAME).
  • An existing name returns 409 MANAGED_OBJECT_EXISTS. SQLite instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
ownerstringNo
encodingstringNo
collationstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "owner": {
      "type": "string"
    },
    "encoding": {
      "type": "string"
    },
    "collation": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "required": [
            "name"
          ],
          "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": {
        "name": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList databasesDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/databases

Lists the logical databases on a PostgreSQL or MySQL instance with owner, size, encoding, collation and whether each is the default or a system database.

  • Requires database:read.
  • The instance must be running. SQLite instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "type": "string",
                    "nullable": true
                  },
                  "sizeBytes": {
                    "type": "number",
                    "nullable": true
                  },
                  "encoding": {
                    "type": "string",
                    "nullable": true
                  },
                  "collation": {
                    "type": "string",
                    "nullable": true
                  },
                  "isDefault": {
                    "type": "boolean"
                  },
                  "isSystem": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "owner",
                  "sizeBytes",
                  "encoding",
                  "collation",
                  "isDefault",
                  "isSystem"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "items"
          ],
          "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": {
        "items": [
          {
            "name": "string",
            "owner": "string",
            "sizeBytes": 0,
            "encoding": "string",
            "collation": "string",
            "isDefault": true,
            "isSystem": true
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDrop a databaseDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/databases/:databaseName/delete

Permanently drops a logical database and its data. The instance's default database cannot be dropped.

  • Requires database:admin.
  • confirmName must equal the database name exactly; otherwise 400 MANAGED_CONFIRMATION_MISMATCH.
  • Without force=true the drop fails while other sessions use the database; force ends those sessions first.
  • The default database returns 409 MANAGED_DEFAULT_DATABASE.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
databaseNamepathYesstring—
confirmNamequeryYesstring—
forcequeryNoboolean—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "dropped": {
              "type": "boolean"
            }
          },
          "required": [
            "dropped"
          ],
          "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": {
        "dropped": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate an access tokenDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/tokens/create

Creates an access token for a SQLite (libSQL) database with full or read-only access and an optional expiry.

  • Requires database:admin.
  • The token value is returned once in this response, sent with cache-control: no-store.
  • name is 1-64 printable characters; expiresInDays is 1-3650 or omitted for no expiry (400 MANAGED_INVALID_EXPIRY).
  • PostgreSQL and MySQL instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
accessread_only | full_accessYes
expiresInDaysnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "access": {
      "type": "string",
      "enum": [
        "read_only",
        "full_access"
      ]
    },
    "expiresInDays": {
      "type": "number"
    }
  },
  "required": [
    "name",
    "access"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "token": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "access": {
                  "type": "string",
                  "enum": [
                    "read_only",
                    "full_access"
                  ]
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "expiresAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "active": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "name",
                "access",
                "createdAt",
                "expiresAt",
                "active"
              ],
              "additionalProperties": false
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "token",
            "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": {
        "token": {
          "id": "string",
          "name": "string",
          "access": "read_only",
          "createdAt": "string",
          "expiresAt": "string",
          "active": true
        },
        "value": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList access tokensDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/tokens

Lists a SQLite (libSQL) database's access tokens, newest first, with name, access, creation and expiry time and whether each is still active. Token values are never returned.

  • Requires database:read.
  • PostgreSQL and MySQL instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "access": {
                    "type": "string",
                    "enum": [
                      "read_only",
                      "full_access"
                    ]
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  },
                  "expiresAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "active": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "access",
                  "createdAt",
                  "expiresAt",
                  "active"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "items"
          ],
          "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": {
        "items": [
          {
            "id": "string",
            "name": "string",
            "access": "read_only",
            "createdAt": "string",
            "expiresAt": "string",
            "active": true
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETERevoke access tokensDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/tokens/:tokenId/delete

Revokes access tokens for a SQLite (libSQL) database. Revocation replaces the signing key, so every token of the instance stops working, not only the one named; connected apps receive a new token automatically.

  • Requires database:admin.
  • Returns how many tokens were revoked and how many connected apps were updated. Create new tokens for other clients afterwards.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
tokenIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "revoked": {
              "type": "number"
            },
            "allTokensRevoked": {
              "const": true,
              "type": "boolean"
            },
            "appsReconnected": {
              "type": "number"
            }
          },
          "required": [
            "revoked",
            "allTokensRevoked",
            "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": {
        "revoked": 0,
        "allTokensRevoked": true,
        "appsReconnected": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate a database userDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/users/create

Creates a user on a PostgreSQL or MySQL database with a generated password and an access preset (admin, read_write or read_only) on the listed databases, or on all databases when none are listed.

  • Requires database:admin.
  • The password is returned once in this response, sent with cache-control: no-store.
  • name uses lowercase letters, numbers and underscores, starts with a letter or underscore, and is at most 63 characters (32 on MySQL) (400 MANAGED_INVALID_USER_NAME).
  • SQLite instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
presetadmin | read_only | read_writeYes
databasesstring[]No
allDatabasesbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "preset": {
      "type": "string",
      "enum": [
        "admin",
        "read_only",
        "read_write"
      ]
    },
    "databases": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "allDatabases": {
      "type": "boolean"
    }
  },
  "required": [
    "name",
    "preset"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "user": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "preset": {
                  "type": "string",
                  "enum": [
                    "custom",
                    "admin",
                    "read_only",
                    "read_write"
                  ]
                },
                "databases": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "allDatabases": {
                  "type": "boolean"
                },
                "isPrimary": {
                  "type": "boolean"
                },
                "canLogin": {
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "preset",
                "databases",
                "allDatabases",
                "isPrimary",
                "canLogin"
              ],
              "additionalProperties": false
            },
            "password": {
              "type": "string"
            }
          },
          "required": [
            "user",
            "password"
          ],
          "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": {
        "user": {
          "name": "string",
          "preset": "custom",
          "databases": [
            "string"
          ],
          "allDatabases": true,
          "isPrimary": true,
          "canLogin": true
        },
        "password": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList database usersDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/users

Lists the users on a PostgreSQL or MySQL database with their access preset, databases, whether they can log in and which one is the primary admin. Passwords are never returned.

  • Requires database:read.
  • SQLite instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "preset": {
                    "type": "string",
                    "enum": [
                      "custom",
                      "admin",
                      "read_only",
                      "read_write"
                    ]
                  },
                  "databases": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "allDatabases": {
                    "type": "boolean"
                  },
                  "isPrimary": {
                    "type": "boolean"
                  },
                  "canLogin": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "preset",
                  "databases",
                  "allDatabases",
                  "isPrimary",
                  "canLogin"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "items"
          ],
          "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": {
        "items": [
          {
            "name": "string",
            "preset": "custom",
            "databases": [
              "string"
            ],
            "allDatabases": true,
            "isPrimary": true,
            "canLogin": true
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDelete a database userDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/users/:userName/delete

Drops a database user after reassigning the objects it owns to reassignOwnedTo, or to the admin user when omitted.

  • Requires database:admin.
  • The primary admin user cannot be deleted (409 MANAGED_PRIMARY_USER).
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
userNamepathYesstring—
reassignOwnedToqueryNostring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "dropped": {
              "type": "boolean"
            }
          },
          "required": [
            "dropped"
          ],
          "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": {
        "dropped": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRotate a user's passwordDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/users/:userName/password/rotate

Sets a new generated password for a database user and returns it.

  • Requires database:admin.
  • The password is returned once in this response, sent with cache-control: no-store.
  • The primary admin user returns 409 MANAGED_PRIMARY_USER; rotate it with POST .../credentials/rotate.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
userNamepathYesstring—

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": {
            "name": {
              "type": "string"
            },
            "password": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "password"
          ],
          "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": {
        "name": "string",
        "password": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
PUTChange a user's accessDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/users/:userName/update

Replaces a database user's access preset and the databases it applies to; an empty databases list grants access to all databases.

  • Requires database:admin.
  • The primary admin user's access cannot be changed (409 MANAGED_PRIMARY_USER).
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
userNamepathYesstring—

JSON request body

FieldType / allowed valuesRequired
presetadmin | read_only | read_writeYes
databasesstring[]No
allDatabasesbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "preset": {
      "type": "string",
      "enum": [
        "admin",
        "read_only",
        "read_write"
      ]
    },
    "databases": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "allDatabases": {
      "type": "boolean"
    }
  },
  "required": [
    "preset"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "required": [
            "name"
          ],
          "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": {
        "name": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

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