Implement user-engine portal foundation

openapi/portal-v1.yaml

@@ -0,0 +1,83 @@
+openapi: 3.1.0
+info:
+  title: user-engine portal API
+  version: 0.1.0
+servers:
+  - url: /api/v1
+security:
+  - verifiedOidc: []
+paths:
+  /me:
+    get:
+      operationId: currentUser
+      responses:
+        "200":
+          description: Current user and linked identities
+        "403":
+          $ref: "#/components/responses/Denied"
+  /registrations:
+    post:
+      operationId: startRegistration
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "201":
+          description: Registration started
+        "403":
+          $ref: "#/components/responses/Denied"
+  /registrations/{registrationId}/complete:
+    post:
+      operationId: completeRegistration
+      parameters:
+        - name: registrationId
+          in: path
+          required: true
+          schema: {type: string}
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "200":
+          description: Registration completed
+        "400":
+          description: Missing verified factors or invalid state
+  /tenants/{tenant}/users:
+    get:
+      operationId: listTenantUsers
+      parameters:
+        - $ref: "#/components/parameters/Tenant"
+        - {name: offset, in: query, schema: {type: integer, minimum: 0}}
+        - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 100}}
+      responses:
+        "200": {description: Tenant-scoped memberships}
+        "403": {$ref: "#/components/responses/Denied"}
+  /tenants/{tenant}/users/{userId}:
+    patch:
+      operationId: updateTenantUserLifecycle
+      parameters:
+        - $ref: "#/components/parameters/Tenant"
+        - name: userId
+          in: path
+          required: true
+          schema: {type: string}
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "200": {description: Tenant account updated}
+        "403": {$ref: "#/components/responses/Denied"}
+components:
+  securitySchemes:
+    verifiedOidc:
+      type: openIdConnect
+      openIdConnectUrl: https://kc.coulomb.social/.well-known/openid-configuration
+  parameters:
+    Tenant:
+      name: tenant
+      in: path
+      required: true
+      schema: {type: string}
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: true
+      schema: {type: string, minLength: 16, maxLength: 200}
+  responses:
+    Denied:
+      description: Caller is unauthenticated or unauthorized