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.