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
- Create one user per application with the narrowest preset:
read_only,read_writeoradmin, for selected databases or all of them. - The new user's password is returned once, by the create or rotate call. Store it before leaving the response.
- 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 -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.
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. nameuses 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 return409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
owner | string | No |
encoding | string | No |
collation | string | No |
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 responseResponse 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse 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. confirmNamemust equal the database name exactly; otherwise400 MANAGED_CONFIRMATION_MISMATCH.- Without
force=truethe drop fails while other sessions use the database;forceends those sessions first. - The default database returns
409 MANAGED_DEFAULT_DATABASE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
databaseName | path | Yes | string | — |
confirmName | query | Yes | string | — |
force | query | No | boolean | — |
Responses
200— Successful responseResponse 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. nameis 1-64 printable characters;expiresInDaysis 1-3650 or omitted for no expiry (400 MANAGED_INVALID_EXPIRY).- PostgreSQL and MySQL instances return
409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
access | read_only | full_access | Yes |
expiresInDays | number | No |
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 responseResponse 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
tokenId | path | Yes | string | — |
Responses
200— Successful responseResponse 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. nameuses 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
preset | admin | read_only | read_write | Yes |
databases | string[] | No |
allDatabases | boolean | No |
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 responseResponse 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
userName | path | Yes | string | — |
reassignOwnedTo | query | No | string | — |
Responses
200— Successful responseResponse 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 withPOST .../credentials/rotate.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
userName | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse 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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
userName | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
preset | admin | read_only | read_write | Yes |
databases | string[] | No |
allDatabases | boolean | No |
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 responseResponse 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" } }