admin/_docs/02_tasks/todo/AZ-196_register_device_endpoint.md

Register Device Endpoint

Task: AZ-196_register_device_endpoint Name: POST /devices endpoint for auto device registration Description: Add POST /devices endpoint to admin API that auto-generates device serial, email, and password for CompanionPC users Complexity: 2 points Dependencies: None Component: Admin API Tracker: AZ-196 Epic: AZ-181

Problem

During Jetson manufacturing, each device needs a unique CompanionPC identity (serial, email, password). Currently the provisioning script generates the email client-side and calls POST /users. The serial/email format should be server-controlled so the admin API is the single source of truth for device numbering.

Outcome

• Single POST /devices endpoint that requires no request body
• Server auto-assigns the next sequential serial (azj-0000, azj-0001, ...)
• Returns plaintext credentials so the provisioning script can embed them in device.conf

Scope

Included

• RegisterDeviceResponse DTO in Azaion.Common/Requests/ with Serial, Email, Password fields
• RegisterDevice method on IUserService / UserService
• POST /devices endpoint in Program.cs with RequireAuthorization(apiAdminPolicy)
• Sequential serial assignment based on most recent CompanionPC user

Excluded

• Changes to the provisioning shell script (handled in loader repo)
• Removing old POST /users endpoint (still used for non-device users)

Implementation Details

Serial number logic

Email format: azj-NNNN@azaion.com where NNNN is zero-padded to 4 digits.

Constants at the top of UserService:

private const int SerialNumberStart = 4;
private const int SerialNumberLength = 4;

RegisterDevice implementation:

1. Query the single most recent CompanionPC user: WHERE role = 'CompanionPC' ORDER BY created_at DESC LIMIT 1
2. If none found, next number is 0000; otherwise extract via Substring(SerialNumberStart, SerialNumberLength), parse, increment
3. Generate email azj-{number:D4}@azaion.com
4. Generate random 32-char hex password: Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLower()
5. Insert User with Role = CompanionPC, IsEnabled = true, password hashed via ToHash()
6. Return RegisterDeviceResponse { Serial, Email, Password (plaintext) }

Endpoint

app.MapPost("/devices",
    async (IUserService userService, CancellationToken cancellationToken)
        => await userService.RegisterDevice(cancellationToken))
    .RequireAuthorization(apiAdminPolicy)
    .WithSummary("Creates a new device");

No request body required.

Acceptance Criteria

AC-1: First device gets serial azj-0000 Given no CompanionPC users exist in the database When POST /devices is called with a valid ApiAdmin JWT Then the response contains serial: "azj-0000", email: "azj-0000@azaion.com", and a 32-char hex password

AC-2: Sequential numbering Given azj-0000 already exists When POST /devices is called again Then the response contains serial: "azj-0001"

AC-3: User persisted with correct role Given POST /devices returned successfully When the users table is queried Then a user exists with the returned email, Role=CompanionPC, IsEnabled=true

AC-4: Password is hashed in DB Given POST /devices returned a plaintext password When the users table is inspected Then PasswordHash contains the SHA-384 hash of the plaintext password, not the plaintext itself

AC-5: Requires ApiAdmin authorization Given a request without a JWT or with a non-ApiAdmin JWT When POST /devices is called Then 401 or 403 is returned