docs/openapi.yaml

@@ -309,6 +309,78 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorMessage'
+  /api/v2/licenses/{licenseKey}/system-name:
+    put:
+      tags: [License]
+      summary: Set a License Key's System Name (Kiosk-only)
+      description: |
+        Sets the human-readable System Name for a License Key. The Kiosk is the
+        only writer; the Portal displays the name read-only. The name is unique
+        per account, compared case-insensitively, when non-null. Idempotent:
+        re-sending the current name returns 200 without a write.
+      operationId: setSystemName
+      parameters:
+        - in: path
+          name: licenseKey
+          required: true
+          schema:
+            type: string
+            pattern: '^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [systemName]
+              properties:
+                systemName:
+                  type: string
+                  minLength: 1
+                  maxLength: 40
+      responses:
+        '200':
+          description: The stored name.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [systemName, systemNameStatus]
+                properties:
+                  systemName:
+                    type: string
+                  systemNameStatus:
+                    type: string
+                    enum: [ok]
+        '400':
+          description: 'Invalid name (`invalid_name`); empty/whitespace is invalid.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
+        '404':
+          description: 'Unknown license (`unknown_license`).'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
+        '409':
+          description: 'Name already used on the account (`name_taken`).'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
+        '429':
+          description: Rate limit exceeded (10 requests per minute per IP).
+          headers:
+            Retry-After:
+              schema:
+                type: integer
+                description: Seconds to wait before retrying.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
   /api/v2/automations/create/account:
     post:
       tags: [Automations]
@@ -505,9 +577,16 @@ components:
           type: string
           format: email
           maxLength: 254
+        systemName:
+          type: string
+          minLength: 1
+          maxLength: 40
+          description: |
+            Optional. The Kiosk's System Name (trimmed). Omitted means the stored
+            name is left untouched; empty/whitespace is invalid, never a clear.
     LicenseResponse:
       type: object
-      required: [key, email_address]
+      required: [key, email_address, systemNameStatus]
       properties:
         key:
           type: string
@@ -515,6 +594,12 @@ components:
         email_address:
           type: string
           format: email
+        systemNameStatus:
+          type: string
+          enum: [ok, unchanged, conflict, invalid]
+          description: |
+            Advisory outcome of the optional `systemName`. Validation itself
+            always succeeds. `unchanged` is returned when the field is omitted.
     ScheduleBlock:
       type: object
       required: