instances added god may help

docs/openapi.yaml

@@ -10,6 +10,8 @@ servers:
 security:
   - BearerAuth: []
 tags:
+  - name: auth
+    description: Public authentication endpoints (no Bearer token required)
   - name: me
   - name: tokens
   - name: users
@@ -17,6 +19,60 @@ tags:
   - name: departments
   - name: roles
 paths:
+  /auth/login:
+    post:
+      tags: [auth]
+      summary: Login with email and password
+      description: |
+        Authenticates a user with email and password and returns a Bearer token.
+        This endpoint is **public** — no Authorization header required.
+
+        The returned token can be used immediately as `Authorization: Bearer <token>`
+        for all subsequent API requests.
+
+        Rate limits (stricter than general API limits):
+        - 10 failed attempts per IP per 10 minutes
+        - 5 failed attempts per email+IP per 15 minutes
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LoginRequest'
+            example:
+              email: user@example.com
+              password: "..."
+              token_name: "My App"
+      responses:
+        '201':
+          description: Login successful — token issued
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LoginResponse'
+        '401':
+          description: Authentication failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalid_credentials:
+                  value:
+                    error: invalid_credentials
+                account_inactive:
+                  value:
+                    error: account_inactive
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/ValidationError'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+
   /me:
     get:
       tags: [me]
@@ -833,6 +889,47 @@ components:
         data:
           type: object
           additionalProperties: true
+    LoginRequest:
+      type: object
+      additionalProperties: false
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+          description: User email address (case-insensitive)
+        password:
+          type: string
+          description: User password
+        token_name:
+          type: string
+          description: Optional label for the issued token (e.g. "iPhone App"). Defaults to "Login".
+          default: Login
+        tenant_uuid:
+          type: string
+          format: uuid
+          description: Optional — scope the issued token to a specific tenant UUID. Must be assigned to the user.
+    LoginResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: object
+          required: [token, token_uuid, expires_at]
+          properties:
+            token:
+              type: string
+              description: Full Bearer token in format `selector:plaintext`. Shown only once — store securely.
+              example: "abc123def:456789..."
+            token_uuid:
+              type: string
+              format: uuid
+              description: UUID of the created token record (use for revocation via /me/tokens)
+            expires_at:
+              type: string
+              format: date-time
+              nullable: true
+              description: UTC expiry timestamp of the token
     RoleWriteRequest:
       type: object
       additionalProperties: false