User
Create, retrieve, update, and delete AIOStreams user configurations.
/api/v1/user
Manage AIOStreams user accounts and configurations. A user is identified by a UUID and protected by a password. These endpoints are the programmatic equivalent of the Save & Install flow in the UI.
All user API requests are rate-limited.
Authentication
All endpoints except HEAD /api/v1/user and POST /api/v1/user (create) authenticate via the standard HTTP Basic scheme:
Authorization: Basic base64(<uuid>:<password>)The <password> may be either the raw user password or the encryptedPassword token returned by POST /api/v1/user and GET /api/v1/user — the server transparently decrypts encrypted tokens.
UUID Aliases
Wherever a UUID is accepted (including as the username in the Authorization header), you may supply a configured alias (a human-readable name mapped to a UUID via the ALIASED_CONFIGURATIONS environment variable) instead. The alias is resolved to the real UUID before processing.
Check User Exists
HEAD /api/v1/user
Checks whether a user exists without returning any sensitive data. Useful for validating a UUID before attempting a full fetch.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | ✅ | UUID (or alias) of the user to check |
Response 200
{
"success": true,
"detail": "User exists",
"error": null,
"data": {
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}Returns an error response if the UUID is not found.
Example
curl -X HEAD "https://your-instance.example.com/api/v1/user?uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"Get User
GET /api/v1/user
Returns the full user configuration and an encrypted copy of the password for use in subsequent requests.
Authentication
Requires Authorization: Basic base64(uuid:password).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
raw | boolean | ❌ | When true, returns the stored config without merging the parent config in. |
Response 200
{
"success": true,
"detail": "User details retrieved successfully",
"error": null,
"data": {
"userData": { },
"encryptedPassword": "<encrypted string>"
}
}| Field | Type | Description |
|---|---|---|
userData | object | Full user configuration object |
encryptedPassword | string | Server-encrypted password — pass this back in the manifest URL instead of the raw password |
Example
curl "https://your-instance.example.com/api/v1/user" \
-H "Authorization: Basic $(echo -n 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:mypassword' | base64)"Create User
POST /api/v1/user
Creates a new user and returns the assigned UUID and an encrypted password.
Request Body
{
"config": { },
"password": "mypassword"
}| Field | Type | Required | Description |
|---|---|---|---|
config | object | ✅ | Full user configuration object |
password | string | ✅ | Password to protect this configuration |
Response 201
{
"success": true,
"detail": "User was successfully created",
"error": null,
"data": {
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"encryptedPassword": "<encrypted string>"
}
}| Field | Type | Description |
|---|---|---|
uuid | string | Assigned UUID — save this, it cannot be recovered |
encryptedPassword | string | Server-encrypted password for use in the manifest URL |
Example
curl -X POST "https://your-instance.example.com/api/v1/user" \
-H "Content-Type: application/json" \
-d '{"config": { }, "password": "mypassword"}'Update User
PUT /api/v1/user
Replaces the stored configuration for an existing user. The request must include the full updated config object — partial updates are not supported.
Authentication
Requires Authorization: Basic base64(uuid:password).
Request Body
{
"config": { }
}| Field | Type | Required | Description |
|---|---|---|---|
config | object | ✅ | Full replacement configuration object |
Response 200
{
"success": true,
"detail": "User updated successfully",
"error": null,
"data": {
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"userData": { }
}
}Example
curl -X PUT "https://your-instance.example.com/api/v1/user" \
-H "Authorization: Basic $(echo -n 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:mypassword' | base64)" \
-H "Content-Type: application/json" \
-d '{"config": { }}'Delete User
DELETE /api/v1/user
Permanently deletes a user and their configuration. This action is irreversible.
Authentication
Requires Authorization: Basic base64(uuid:password).
Response 200
{
"success": true,
"detail": "User deleted successfully",
"error": null,
"data": null
}Example
curl -X DELETE "https://your-instance.example.com/api/v1/user" \
-H "Authorization: Basic $(echo -n 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:mypassword' | base64)"