Eformogi Account API

openapi: 3.2.0
info:
  title: Eformogi Account API
  version: 33.5.1
  description: 'Eformogi is a record of learning the student owns, witnessed by the adults who were there, verifiable at one link with no login, and issued by the schools and counselors who hold the learners. The family-issued receipt (`tr_`) is a Witness Transcript. This document describes the machine-readable surface: verification, witness attestation, consent, the agent protocol, and the issuer rail (enrollment, roster, declared courses, and the family side that folds them into the transcript). The open record format itself is published at https://eformogi.com/spec.'
  contact:
    url: https://eformogi.com
  license:
    name: Proprietary
servers:
- url: https://eformogi.com
  description: Production
tags:
- name: Account
  description: User account management
paths:
  /api/delete-account:
    post:
      summary: Delete user account
      description: Permanently deletes the authenticated user's account and all associated data. Requires confirmation phrase. GDPR Art. 17 compliant.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - confirmation
              properties:
                confirmation:
                  type: string
                  enum:
                  - DELETE MY ACCOUNT
                  description: Confirmation phrase
      responses:
        '200':
          description: Account permanently deleted
        '400':
          description: Confirmation phrase required
        '401':
          description: Authentication required
      operationId: postApiDeleteAccount
      x-operation-id-source: derived
  /api/user-activity:
    get:
      summary: Get user activity dashboard
      description: Returns comprehensive activity history including documents, form fills, AI usage, credentials, shares, audit events, and monthly trends.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Activity data including tier, documents, fills, ai, shares, credentials, auditEvents, monthlyTrend
        '401':
          description: Authentication required
        '429':
          description: Rate limited (30/min)
      operationId: getApiUserActivity
      x-operation-id-source: derived
  /api/notifications:
    get:
      summary: Get notifications
      description: Returns paginated list of user notifications with unread count. Supports filtering by read/unread status.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
        description: Max notifications to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: Pagination offset
      - name: unread
        in: query
        schema:
          type: boolean
        description: Filter to unread only
      responses:
        '200':
          description: Notification list with total and unread counts
        '401':
          description: Authentication required
        '429':
          description: Rate limited (60/min)
      operationId: getApiNotifications
      x-operation-id-source: derived
    patch:
      summary: Mark notifications as read
      description: Mark specific notifications or all notifications as read.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                all:
                  type: boolean
                  description: Mark all as read
                ids:
                  type: array
                  items:
                    type: string
                  description: Specific notification IDs to mark read
      responses:
        '200':
          description: Notifications marked as read
        '401':
          description: Authentication required
      operationId: patchApiNotifications
      x-operation-id-source: derived
  /api/data-export:
    get:
      summary: Export all user data (GDPR Art. 20)
      description: Returns all personal data in JSON or CSV format. Includes vault data, documents, form fills, share links, credentials, consent receipts, audit log, notifications, AI usage, and family members.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - csv
          default: json
        description: Export format
      responses:
        '200':
          description: Complete data export with Content-Disposition header for download
        '401':
          description: Authentication required
        '429':
          description: Rate limited (5/hour)
      operationId: getApiDataExport
      x-operation-id-source: derived
  /api/security-events:
    get:
      summary: Get security events
      description: 'Returns recent security-related events on the user''s account: data access, share link views, credential events, consent changes, and account activity. All events are from the audit log.'
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 50
        description: Number of events to return (max 50)
      responses:
        '200':
          description: Security events with summary stats and account info
        '401':
          description: Authentication required
      operationId: getApiSecurityEvents
      x-operation-id-source: derived
  /api/notification-preferences:
    get:
      summary: Get notification preferences
      description: Returns the authenticated user's notification preferences with type descriptions.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current preferences and available notification types
        '401':
          description: Authentication required
      operationId: getApiNotificationPreferences
      x-operation-id-source: derived
    patch:
      summary: Update notification preferences
      description: Toggle notification types on/off. Merged with existing preferences.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - preferences
              properties:
                preferences:
                  type: object
                  description: Map of notification types to boolean values
                  example:
                    share_viewed: true
                    system: false
      responses:
        '200':
          description: Preferences updated
        '400':
          description: Invalid type names or values
        '401':
          description: Authentication required
      operationId: patchApiNotificationPreferences
      x-operation-id-source: derived
  /api/feedback:
    post:
      summary: Submit feedback
      description: Submit user feedback. Authentication optional, anonymous submissions accepted.
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - message
              properties:
                type:
                  type: string
                  enum:
                  - bug
                  - feature
                  - general
                  - question
                message:
                  type: string
                  minLength: 5
                  maxLength: 5000
                page:
                  type: string
                  description: Page where feedback was submitted
                metadata:
                  type: object
                  description: Optional browser/device metadata
      responses:
        '200':
          description: Feedback submitted successfully
        '400':
          description: Invalid type or message length
        '429':
          description: Rate limited
      operationId: postApiFeedback
      x-operation-id-source: derived
  /api/api-keys:
    get:
      summary: List API keys
      description: Returns the authenticated user's active API keys with masked previews.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of active API keys
        '401':
          description: Authentication required
      operationId: getApiApiKeys
      x-operation-id-source: derived
    post:
      summary: Create API key
      description: Generate a new personal API key. The full key is only returned once at creation.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                  description: Friendly name for the key
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 365
      responses:
        '200':
          description: API key created with secret (shown once)
        '400':
          description: Maximum 5 active keys reached
        '401':
          description: Authentication required
      operationId: postApiApiKeys
      x-operation-id-source: derived
    delete:
      summary: Revoke API key
      description: Revoke an API key by ID. Cannot be undone.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: Key ID to revoke
      responses:
        '200':
          description: API key revoked
        '401':
          description: Authentication required
        '404':
          description: Key not found
      operationId: deleteApiApiKeys
      x-operation-id-source: derived
  /api/sessions:
    get:
      summary: List active sessions
      description: Returns active sessions for the authenticated user with device/browser info and IP.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of active sessions
        '401':
          description: Authentication required
      operationId: getApiSessions
      x-operation-id-source: derived
    delete:
      summary: Revoke a session
      description: Revoke an active session by ID, signing out that device remotely.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: Session event ID to revoke
      responses:
        '200':
          description: Session revoked
        '401':
          description: Authentication required
        '404':
          description: Session not found
      operationId: deleteApiSessions
      x-operation-id-source: derived
  /api/data-retention:
    get:
      summary: Get retention policies
      description: Returns the user's data retention policies for each category.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current retention policies with category metadata
        '401':
          description: Authentication required
      operationId: getApiDataRetention
      x-operation-id-source: derived
    patch:
      summary: Update retention policies
      description: Update retention periods for specific data categories.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - policies
              properties:
                policies:
                  type: object
                  description: Map of category keys to retention_days values
      responses:
        '200':
          description: Policies updated
        '400':
          description: Invalid retention period
        '401':
          description: Authentication required
      operationId: patchApiDataRetention
      x-operation-id-source: derived
    post:
      summary: Preview or apply data retention
      description: Preview records eligible for deletion or apply retention policies. Use ?action=preview or ?action=apply.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: action
        in: query
        required: true
        schema:
          type: string
          enum:
          - preview
          - apply
      responses:
        '200':
          description: Preview results or deletion confirmation
        '401':
          description: Authentication required
      operationId: postApiDataRetention
      x-operation-id-source: derived
  /api/trusted-devices:
    get:
      summary: List trusted devices
      description: Returns all trusted (non-revoked) devices for the authenticated user, with current device detection.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Array of trusted devices with browser, OS, device type, and expiration info
        '401':
          description: Authentication required
      operationId: getApiTrustedDevices
      x-operation-id-source: derived
    post:
      summary: Trust current device
      description: Register the current browser/device as trusted. Maximum 10 trusted devices. Default expiration 90 days.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Custom device name
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 365
                  description: Days until trust expires (default 90)
      responses:
        '200':
          description: Device trusted successfully
        '400':
          description: Maximum device limit reached
        '401':
          description: Authentication required
      operationId: postApiTrustedDevices
      x-operation-id-source: derived
    delete:
      summary: Remove trusted device
      description: Revoke trust for a specific device by ID.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: Device ID to remove
      responses:
        '200':
          description: Device trust revoked
        '401':
          description: Authentication required
        '404':
          description: Device not found
      operationId: deleteApiTrustedDevices
      x-operation-id-source: derived
  /api/login-history:
    get:
      summary: Get login history
      description: Returns paginated sign-in events with device info, IP, status, and authentication method.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Max results
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Pagination offset
      - name: status
        in: query
        schema:
          type: string
          enum:
          - all
          - success
          - failed
          default: all
        description: Filter by status
      responses:
        '200':
          description: Paginated login history with summary stats
        '401':
          description: Authentication required
      operationId: getApiLoginHistory
      x-operation-id-source: derived
  /api/webhooks:
    get:
      summary: List webhooks
      description: Returns all configured webhooks for the authenticated user, plus available event types.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Array of webhooks with event subscriptions, status, and available events list
        '401':
          description: Authentication required
      operationId: getApiWebhooks
      x-operation-id-source: derived
    post:
      summary: Create webhook or send test ping
      description: Create a new webhook endpoint (max 5) or send a test ping with ?action=test. HTTPS URLs only. Returns signing secret on creation.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: action
        in: query
        schema:
          type: string
          enum:
          - test
        description: Set to "test" to send a test ping instead of creating
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Webhook name
                url:
                  type: string
                  format: uri
                  description: HTTPS endpoint URL
                events:
                  type: array
                  items:
                    type: string
                  description: Event types to subscribe to
                id:
                  type: string
                  description: Webhook ID (for test ping only)
      responses:
        '200':
          description: Webhook created with signing secret, or test ping result
        '400':
          description: Invalid URL, missing events, or limit reached
        '401':
          description: Authentication required
      operationId: postApiWebhooks
      x-operation-id-source: derived
    delete:
      summary: Delete webhook
      description: Permanently delete a webhook endpoint.
      tags:
      - Account
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: Webhook ID to delete
      responses:
        '200':
          description: Webhook deleted
        '401':
          description: Authentication required
        '404':
          description: Webhook not found
      operationId: deleteApiWebhooks
      x-operation-id-source: derived
  /api/page-handle:
    post:
      summary: Claim or rename a page handle (signed-in)
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Claimed
        '409':
          description: Taken
      operationId: postApiPageHandle
      x-operation-id-source: derived
  /api/push-subscribe:
    post:
      summary: Register this browser for recognition-delivery push (signed-in)
      description: Stores or updates the caller's own web push subscription (endpoint, keys.p256dh, keys.auth). The endpoint must be https and match a real browser push service (FCM, Apple, Windows, or Mozilla); anything else is refused before it is ever stored. On a conflict (the same browser subscription already has a row), ownership moves to the caller and failed_count resets, the honest shared-device handoff. At most 5 subscriptions are kept per caller, oldest evicted.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - subscription
              properties:
                subscription:
                  type: object
                  required:
                  - endpoint
                  - keys
                  properties:
                    endpoint:
                      type: string
                      format: uri
                      description: https, and must match a supported push service host (fcm.googleapis.com, *.push.apple.com, *.notify.windows.com, *.push.services.mozilla.com).
                    keys:
                      type: object
                      required:
                      - p256dh
                      - auth
                      properties:
                        p256dh:
                          type: string
                        auth:
                          type: string
      responses:
        '200':
          description: Stored or updated
        '400':
          description: Bad shape, or the endpoint is not a supported push service
        '401':
          description: No or bad token
        '503':
          description: push_subscriptions is not migrated yet
      operationId: postApiPushSubscribe
      x-operation-id-source: derived
    delete:
      summary: Remove this browser's push subscription (signed-in)
      description: Best-effort cleanup, called from the sign-out flow before the session drops (and from the toggle on an explicit turn-off), so a shared device can never keep notifying about the signed-out student's items. Removes only the caller's own row for the given endpoint; removing an already-absent row is still 200.
      tags:
      - Account
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - endpoint
              properties:
                endpoint:
                  type: string
                  format: uri
      responses:
        '200':
          description: Removed (or already absent)
        '400':
          description: endpoint required
        '401':
          description: No or bad token
        '503':
          description: push_subscriptions is not migrated yet
      operationId: deleteApiPushSubscribe
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase JWT access token
    orgApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Institutional org API key. Use "Bearer efg_org_..." or "Api-Key efg_org_..." header. Keys are scoped to specific data categories.