BudgethostAPI DOCUMENTATION
API v1OpenAPI
DATABASE AND ACCESS APIREST / JSON

Manage databases and access

Create and manage private SQL databases, database users, SFTP accounts and container SSH access within your slice.

Use a slice token to manage resources in that slice. Service deployment tokens do not grant these operations. The base path is:

https://api.budgethost.io/v1/deploy/slices/{sliceId}

Choose Bash, PowerShell 7.4+ or Node.js, as in the other guides. First complete Connect to your slice in the same language. That setup loads your slice credentials and defines the API helpers, slice base URL and private request directory used below. For Node.js, put the setup and your selected examples in the same .mjs file.

Replace the uppercase ID and public-key placeholders before sending a request. Keep each saved request, idempotency key and response for recovery. Reuse that directory and the unchanged request when retrying; use a new request directory for a different resource. No example prints account passwords.

Every request uses Authorization: Bearer <slice-token>. POST, PATCH and DELETE requests require a saved X-Idempotency-Key. Send JSON request bodies directly, without a data wrapper. Responses use the normal data envelope and Cache-Control: no-store.

Permissions#

Action Grant
List/get services, databases or accounts; poll operations read
Create a managed database service applications:manage and storage:manage
Rename a managed service's label applications:manage
Decommission a managed service applications:delete
Create/edit databases and database users, read user credentials, rotate passwords databases:manage
Delete databases and database users databases:delete
Create/edit SFTP and SSH accounts, read credentials, rotate passwords access:manage
Delete SFTP and SSH accounts access:delete

The four database/access grants are explicit opt-ins. Existing tokens receive no new grants. Enable the required permissions on a slice token before using these endpoints. A token that can read inventory cannot read passwords without its corresponding management grant.

Managed database service#

Discover available types and create a private MariaDB runtime using the existing managed-service creation workflow. Configuration does not start the runtime; apply it separately with deploy permission.

Method Path Purpose
GET /managed-service-types Discover supported types
POST /managed-services Configure a managed runtime and its initial database
GET /managed-services List managed runtimes and observed state
GET /managed-services/{serviceId} Read one managed runtime
PATCH /managed-services/{serviceId} Edit display_name
DELETE /managed-services/{serviceId} Decommission the runtime

PATCH accepts {"display_name":"Reporting SQL"}. It updates the label without restarting the service. Approved images, root credentials and inherited slice limits remain platform-managed. SQL database names cannot be renamed by PATCH.

DELETE uses normal service decommissioning and returns HTTP 202. Its databases and account registrations are removed as part of that workflow. Persistent storage is retained and listed in retained_storage_ids; this is not an erase of the retained SQL files. Use the separate storage-deletion workflow when the retained volume is no longer needed. Other services in the slice are unaffected.

Databases and users#

Each collection supports GET and POST. Each resource supports GET, PATCH and DELETE:

/databases
/databases/{resourceId}
/database-users
/database-users/{resourceId}

GET collections return data.items. They contain only resources whose SQL service belongs to this slice and tenant. Use service_id from the managed service list or slice inventory; a database ID is a separate resource identity.

Create a database on an existing MariaDB service:

Linux / macOS - Bash
cat > "$STATE/reporting-database-request.json" <<'JSON'
{"service_id":"SQL_SERVICE_ID","database_name":"reporting","display_name":"Reporting"}
JSON
if [ ! -f "$STATE/reporting-database.key" ]; then uuid > "$STATE/reporting-database.key"; fi
slice_api --request POST "$SLICE_BASE/databases" \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $(cat "$STATE/reporting-database.key")" \
  --data-binary @"$STATE/reporting-database-request.json" > "$STATE/reporting-database.json"
jq .data "$STATE/reporting-database.json"
Windows - PowerShell 7.4+
Save-Json @{
    service_id = 'SQL_SERVICE_ID'
    database_name = 'reporting'
    display_name = 'Reporting'
} "$State/reporting-database-request.json"
New-Key "$State/reporting-database.key"
$database = Invoke-Api -Uri "$SliceBase/databases" -Token $SliceToken -Method Post `
    -KeyFile "$State/reporting-database.key" -BodyFile "$State/reporting-database-request.json"
Save-Json $database "$State/reporting-database.json"
$database.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
await saveJson(`${state}/reporting-database-request.json`, {
  service_id: 'SQL_SERVICE_ID', database_name: 'reporting', display_name: 'Reporting',
});
await newKey(`${state}/reporting-database.key`);
const database = await api(`${sliceBase}/databases`, {
  token: sliceToken, method: 'POST', keyFile: `${state}/reporting-database.key`,
  bodyFile: `${state}/reporting-database-request.json`,
});
await saveJson(`${state}/reporting-database.json`, database);
console.log(database.data);

Save data.resource.id and data.operation_id from HTTP 202. Create an account for that database using the saved response:

Linux / macOS - Bash
DATABASE_ID=$(jq -er '.data.resource.id' "$STATE/reporting-database.json")
jq -n --arg database_id "$DATABASE_ID" \
  '{service_id:"SQL_SERVICE_ID",database_id:$database_id,username:"reporter",display_name:"Reporting access"}' \
  > "$STATE/reporting-user-request.json"
if [ ! -f "$STATE/reporting-user.key" ]; then uuid > "$STATE/reporting-user.key"; fi
slice_api --request POST "$SLICE_BASE/database-users" \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $(cat "$STATE/reporting-user.key")" \
  --data-binary @"$STATE/reporting-user-request.json" > "$STATE/reporting-user.json"
jq .data "$STATE/reporting-user.json"
Windows - PowerShell 7.4+
$databaseId = (Read-Json "$State/reporting-database.json").data.resource.id
Save-Json @{
    service_id = 'SQL_SERVICE_ID'
    database_id = $databaseId
    username = 'reporter'
    display_name = 'Reporting access'
} "$State/reporting-user-request.json"
New-Key "$State/reporting-user.key"
$databaseUser = Invoke-Api -Uri "$SliceBase/database-users" -Token $SliceToken -Method Post `
    -KeyFile "$State/reporting-user.key" -BodyFile "$State/reporting-user-request.json"
Save-Json $databaseUser "$State/reporting-user.json"
$databaseUser.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
const databaseId = (await readJson(`${state}/reporting-database.json`)).data.resource.id;
await saveJson(`${state}/reporting-user-request.json`, {
  service_id: 'SQL_SERVICE_ID', database_id: databaseId,
  username: 'reporter', display_name: 'Reporting access',
});
await newKey(`${state}/reporting-user.key`);
const databaseUser = await api(`${sliceBase}/database-users`, {
  token: sliceToken, method: 'POST', keyFile: `${state}/reporting-user.key`,
  bodyFile: `${state}/reporting-user-request.json`,
});
await saveJson(`${state}/reporting-user.json`, databaseUser);
console.log(databaseUser.data);

Database names use lowercase letters, digits and underscores, start with a letter and are at most 64 characters. System schemas are reserved. SQL usernames use the same characters and are 3-32 characters; administrative identities such as root are reserved. The account receives ALL on its selected application schema, rather than global/root privileges. Passwords are generated by the API.

Database PATCH edits display_name; supplying the unchanged database_name is also accepted. Renaming or moving SQL schemas is unsupported. Database-user PATCH accepts display_name, username, enabled and database_id. Its target database must remain on the same SQL service. Start the SQL service before changing a username: otherwise the API returns 409 DATABASE_RUNTIME_REQUIRED without changing the account. A rename queues removal of the old login during runtime apply; poll the operation until it succeeds. Setting enabled:false queues revocation. Update affected application connection settings separately; these account operations do not redeploy application clients.

Delete users before deleting their database. Database users and application environment bindings block deletion. Remove the database from backup groups and schedules first, and wait for active backup/restore work. Historical backups are retained. A required managed-service or bundle database cannot be deleted individually: decommission its owning service instead. Start a stopped SQL service before deleting already-applied databases or users, so the SQL drop can be queued. An unapplied registration can be removed before its first deployment.

SFTP and container SSH accounts#

The same collection/resource methods are available at:

/sftp-accounts
/sftp-accounts/{resourceId}
/ssh-access-accounts
/ssh-access-accounts/{resourceId}

SFTP requires an existing storage-sftp member service and an attached storage path already marked exportable over SFTP. It does not enable arbitrary storage exports or accept a host filesystem path. Use the storage ID and path key from the configured storage attachment. If no SFTP service/export exists, contact support to configure that target first.

Create an SFTP account for that configured target:

Linux / macOS - Bash
cat > "$STATE/sftp-account-request.json" <<'JSON'
{
  "service_id": "SFTP_SERVICE_ID",
  "storage_id": "STORAGE_ID",
  "path_key": "www",
  "external_username": "site_uploads",
  "display_name": "Site uploads",
  "enabled": true
}
JSON
if [ ! -f "$STATE/sftp-account.key" ]; then uuid > "$STATE/sftp-account.key"; fi
slice_api --request POST "$SLICE_BASE/sftp-accounts" \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $(cat "$STATE/sftp-account.key")" \
  --data-binary @"$STATE/sftp-account-request.json" > "$STATE/sftp-account.json"
jq .data "$STATE/sftp-account.json"
Windows - PowerShell 7.4+
Save-Json @{
    service_id = 'SFTP_SERVICE_ID'
    storage_id = 'STORAGE_ID'
    path_key = 'www'
    external_username = 'site_uploads'
    display_name = 'Site uploads'
    enabled = $true
} "$State/sftp-account-request.json"
New-Key "$State/sftp-account.key"
$sftpAccount = Invoke-Api -Uri "$SliceBase/sftp-accounts" -Token $SliceToken -Method Post `
    -KeyFile "$State/sftp-account.key" -BodyFile "$State/sftp-account-request.json"
Save-Json $sftpAccount "$State/sftp-account.json"
$sftpAccount.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
await saveJson(`${state}/sftp-account-request.json`, {
  service_id: 'SFTP_SERVICE_ID', storage_id: 'STORAGE_ID', path_key: 'www',
  external_username: 'site_uploads', display_name: 'Site uploads', enabled: true,
});
await newKey(`${state}/sftp-account.key`);
const sftpAccount = await api(`${sliceBase}/sftp-accounts`, {
  token: sliceToken, method: 'POST', keyFile: `${state}/sftp-account.key`,
  bodyFile: `${state}/sftp-account-request.json`,
});
await saveJson(`${state}/sftp-account.json`, sftpAccount);
console.log(sftpAccount.data);

SFTP PATCH accepts display_name, storage_id, path_key, external_username and enabled. Storage must still be attached and exportable through that same service. Existing storage placement and quota checks apply.

SSH accounts target a Compose component of an existing eligible member service. This creates container access, not a host operating-system user. Arbitrary container IDs, host paths, privileged gateway settings and private keys are not accepted. Create an SSH account with your OpenSSH public key:

Linux / macOS - Bash
cat > "$STATE/ssh-account-request.json" <<'JSON'
{
  "service_id": "APPLICATION_SERVICE_ID",
  "compose_service_name": "app",
  "external_username": "site_maintenance",
  "display_name": "Maintenance",
  "shell": "sh",
  "working_dir": "/app",
  "enabled": true,
  "authorized_keys": ["ssh-ed25519 YOUR_BASE64_PUBLIC_KEY maintenance"]
}
JSON
if [ ! -f "$STATE/ssh-account.key" ]; then uuid > "$STATE/ssh-account.key"; fi
slice_api --request POST "$SLICE_BASE/ssh-access-accounts" \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $(cat "$STATE/ssh-account.key")" \
  --data-binary @"$STATE/ssh-account-request.json" > "$STATE/ssh-account.json"
jq .data "$STATE/ssh-account.json"
Windows - PowerShell 7.4+
Save-Json @{
    service_id = 'APPLICATION_SERVICE_ID'
    compose_service_name = 'app'
    external_username = 'site_maintenance'
    display_name = 'Maintenance'
    shell = 'sh'
    working_dir = '/app'
    enabled = $true
    authorized_keys = @('ssh-ed25519 YOUR_BASE64_PUBLIC_KEY maintenance')
} "$State/ssh-account-request.json"
New-Key "$State/ssh-account.key"
$sshAccount = Invoke-Api -Uri "$SliceBase/ssh-access-accounts" -Token $SliceToken -Method Post `
    -KeyFile "$State/ssh-account.key" -BodyFile "$State/ssh-account-request.json"
Save-Json $sshAccount "$State/ssh-account.json"
$sshAccount.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
await saveJson(`${state}/ssh-account-request.json`, {
  service_id: 'APPLICATION_SERVICE_ID', compose_service_name: 'app',
  external_username: 'site_maintenance', display_name: 'Maintenance',
  shell: 'sh', working_dir: '/app', enabled: true,
  authorized_keys: ['ssh-ed25519 YOUR_BASE64_PUBLIC_KEY maintenance'],
});
await newKey(`${state}/ssh-account.key`);
const sshAccount = await api(`${sliceBase}/ssh-access-accounts`, {
  token: sliceToken, method: 'POST', keyFile: `${state}/ssh-account.key`,
  bodyFile: `${state}/ssh-account-request.json`,
});
await saveJson(`${state}/ssh-account.json`, sshAccount);
console.log(sshAccount.data);

SSH PATCH accepts those fields except service_id. Supported shells are sh and bash; the working directory is an absolute container path, or null to clear it. Up to 64 OpenSSH public keys are accepted. External usernames are unique across access accounts and use lowercase letters, digits, underscores and hyphens, starting with a lowercase letter or underscore (1-32 characters). Connection hostname/port come from the configured public SSH gateway.

Access mutations refresh the relevant SFTP or SSH gateway backend and its public routing. Deleting an account removes its managed password. Confirm queued refresh work completes before treating a deleted or disabled login as revoked.

Credentials and password rotation#

For database-users, sftp-accounts and ssh-access-accounts:

GET  /{collection}/{resourceId}/credentials
POST /{collection}/{resourceId}/rotate-password

Credential reads return data.id, data.username and the current generated data.password. Keep the response out of logs and store it securely. Root database credentials, secret IDs and unrelated account passwords are not exposed.

Rotation has an empty body and requires an idempotency key. Its HTTP 202 response contains resource and operation identifiers, without a plaintext password. Read the account's /credentials endpoint separately to obtain the generated value; wait for runtime application before expecting it to authenticate. Same-key retries return the original receipt without rotating a second time. A credential GET always returns the current value, including after a later successful rotation.

Runtime status, retries and failures#

Database and account mutations return HTTP 202 with data.resource, data.operation_id, data.work_order_ids, data.status and data.runtime_changed:false. status:queued means runtime work was dispatched; status:configured means desired state is saved and requires a later deployment. Neither response alone proves the new credentials or database are usable.

Poll GET /operations/{operationId} with read permission. Its top-level data.status describes the configuration receipt. For database/account mutations, data.runtime_status separately reports configured, queued, succeeded, failed or unavailable, with bounded data.work_orders statuses/codes. Missing or no-longer-retained work is unavailable, rather than assumed successful. Service/database GETs report recorded state and observation timestamps.

Retry a lost response using the same key, URL and body. A successful retry returns the same resource/operation. A changed request under the same key returns IDEMPOTENCY_CONFLICT. Revoked tokens, removed grants, changed ownership and resources outside the slice remain rejected, including on receipt replays.

If a mutation fails after a resource was saved or removed, inspect the returned operation_id. The receipt preserves the resource identity and any intended SQL removal name without storing passwords. SLICE_OPERATION_INCOMPLETE prevents an automatic duplicate create/rotation. Contact support to reconcile a partial operation; a new key must not be used to bypass it. Runtime errors after dispatch are reported through runtime_status and work_orders; configuration receipt success is not runtime success.