api login method

interface/api.yaml

@@ -29,6 +29,8 @@ tags:
 paths:
   /accounts/login:
     $ref: ./api/accounts/auth_login.yaml
+  /accounts/login/api:
+    $ref: ./api/accounts/auth_login_api.yaml
   /accounts/rotate:
     $ref: ./api/accounts/auth_rotate.yaml
   /accounts/refresh:

interface/api/accounts/auth_login_api.yaml

@@ -0,0 +1,30 @@
+post:
+  tags: [Accounts, Auth]
+  summary: API login using email/password and client credentials
+  description: |
+    Validates account credentials and eligible API client credentials, then returns final auth payload.
+    This endpoint bypasses login OTP/2FA and is intended only for approved API clients.
+    If the client definition includes `allowedCIDRs`, request source IP must match one of those CIDRs.
+  operationId: accountsApiLogin
+  requestBody:
+    $ref: ./bodies/auth.yaml#/components/requestBodies/ApiLoginBody
+  responses:
+    '200':
+      description: Login successful
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/auth.yaml#/components/schemas/LoginData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/accounts/bodies/auth.yaml

@@ -6,6 +6,12 @@ components:
         application/json:
           schema:
             $ref: ../request/auth.yaml#/components/schemas/LoginRequest
+    ApiLoginBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/auth.yaml#/components/schemas/ApiLoginRequest
 
     RefreshTokenBody:
       required: true

interface/api/accounts/request/auth.yaml

@@ -8,10 +8,26 @@ components:
       properties:
         clientId:
           type: string
+          description: Client identifier bound to refresh token lifecycle and client policy checks.
         deviceId:
           type: string
         login:
           $ref: ../../../models/auth/login_data.yaml#/components/schemas/LoginData
 
+    ApiLoginRequest:
+      allOf:
+        - $ref: ./auth.yaml#/components/schemas/LoginRequest
+        - type: object
+          additionalProperties: false
+          required:
+            - clientId
+            - deviceId
+            - clientSecret
+          properties:
+            clientSecret:
+              type: string
+              format: password
+              description: Client secret for `client_secret_post` authentication.
+
     RefreshTokenRequest:
       $ref: ../../../models/auth/client_refresh_token.yaml#/components/schemas/ClientRefreshToken