reqistry-dev Auth API

openapi: 3.2.0
info:
  title: Public APIs — Mobile Client Auth API
  description: 'API reference for the Public APIs Flutter mobile app. Includes anonymous device auth, email/password account linking, profile management, bookmarks, folders, discovery, categories, search, and legacy JSON endpoints.


    ## Authentication


    Bearer-protected endpoints require:


    ```

    Authorization: Bearer

    ```


    Tokens are obtained via `POST /v1/auth/anonymous` or `POST /v1/auth/login-email`.


    Public endpoints (no token required): `POST /submit`, `POST /v1/apis` (auth optional, enables submission attribution), `POST /v1/auth/anonymous`, `POST /v1/auth/refresh`, `POST /v1/auth/revoke`, `POST /v1/auth/login-email`, `GET /v1/recently-added`, `GET /v1/recommend` (auth optional, personalizes with bookmarks), `GET /v1/apis/{slug}`, `GET /v1/apis/{id}/alternatives`, `GET /v1/trust-scores/{id}`, `GET /v1/apis/compare`, `GET /v1/change-feed`, `GET /v1/use-case-collections`, categories (unversioned and `/v1` aliases), `GET /search`, `GET /metadata`, `POST /track`, and `POST /admin/v1/contact-messages`. Every other `/v1/*` operation requires a Bearer token.


    ## Account Types

    - **Anonymous**: Device-only, no email. Data tied to device fingerprint.

    - **Email-linked**: Has email + password. Can login from any device. Data merges on link.


    ## Token Lifecycle

    - **Access token**: 15 minutes, used for API requests

    - **Refresh token**: 30 days, used to rotate access tokens

    - Refreshing a token invalidates the old one (single-use rotation)

    - Revoking deactivates all tokens for a device'
  version: 1.0.0
  contact:
    name: Public APIs
    url: '---'
servers:
- url: http://localhost:4000
  description: Local development
- url: '---'
  description: Production
tags:
- name: Auth
  description: Anonymous device authentication (v1)
paths:
  /v1/auth/anonymous:
    post:
      tags:
      - Auth
      summary: Get anonymous device token
      description: 'Create or resume an anonymous device session. If the device has an active refresh token, returns a new access token without creating a new session (200). Otherwise, creates a new device session with refresh + access tokens (201).


        This is the entry point for the Flutter app — no account creation required.'
      operationId: anonymousAuth
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnonymousAuthRequest'
      responses:
        '200':
          description: Existing device — tokens re-issued (refreshToken is null)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '201':
          description: New device created — full token pair issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
  /v1/auth/refresh:
    post:
      tags:
      - Auth
      summary: Refresh access token
      description: Rotate the refresh token and issue a new access token. The old refresh token is invalidated (single-use rotation).
      operationId: refreshToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: New tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '401':
          description: Invalid or expired refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/revoke:
    post:
      tags:
      - Auth
      summary: Revoke device session
      description: Deactivate all tokens for a device. The device will need to re-authenticate via `/v1/auth/anonymous`.
      operationId: revokeSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
      responses:
        '200':
          description: Session revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeResponse'
  /v1/auth/link-email:
    post:
      tags:
      - Auth
      summary: Link email/password to anonymous account
      description: Links the current anonymous device to an email/password account. If the email already exists on another device, bookmarks and folders are merged to that device and the current device is deactivated (user receives new tokens for the existing account). After linking, the user can login from any device via `/v1/auth/login-email`.
      operationId: linkEmail
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkEmailRequest'
      responses:
        '200':
          description: Email linked (or account merged)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkEmailResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Access token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/login-email:
    post:
      tags:
      - Auth
      summary: Login with email/password
      description: Authenticate with email and password. Returns access + refresh tokens. Only works for accounts that have been linked via `/v1/auth/link-email`.
      operationId: loginEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailLoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/me:
    get:
      tags:
      - Auth
      summary: Get current user profile + stats
      description: Returns full user profile including name, email (if linked), auth provider, device info, and aggregated stats (bookmarks count, folders count, folder items count, days since creation, member since date).
      operationId: getMe
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User profile with stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Auth
      summary: Update user profile
      description: Update the current user's profile. Currently only supports updating the name field.
      operationId: updateMe
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
      responses:
        '200':
          description: Profile updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Access token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Auth
      summary: Delete account and all data
      description: Permanently delete the current user's account and all associated data including bookmarks, folders, FCM tokens, and reports. This action is irreversible.
      operationId: deleteMe
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Account deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          description: Access token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RevokeRequest:
      type: object
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
    RefreshTokenRequest:
      type: object
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
    LinkEmailResponse:
      type: object
      description: Response after linking email. If merged, includes new tokens for the existing account.
      properties:
        success:
          type: boolean
        message:
          type: string
        authProvider:
          type: string
          enum:
          - email
        merged:
          type: boolean
          description: True if data was merged into an existing email account
        accessToken:
          type: string
          description: New access token (only present if merged)
        refreshToken:
          type: string
          description: New refresh token (only present if merged)
        expiresIn:
          type: integer
          description: Token TTL in seconds (only present if merged)
    AuthTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT access token (15min expiry)
        refreshToken:
          type:
          - string
          - 'null'
          description: Refresh token (30 day expiry, single-use). Null when resuming an existing device session — keep the stored token.
        expiresIn:
          type: integer
          description: Access token TTL in seconds
          example: 900
        tokenType:
          type: string
          example: Bearer
        device:
          type: object
          properties:
            id:
              type: string
              format: uuid
            deviceFingerprint:
              type: string
            createdAt:
              type: string
              format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    EmailLoginRequest:
      type: object
      required:
      - email
      - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
    AnonymousAuthRequest:
      type: object
      properties:
        deviceId:
          type: string
          description: Optional client-generated device ID
        name:
          type: string
          description: Optional display name
        deviceInfo:
          type: object
          properties:
            platform:
              type: string
              description: ios, android, web
            model:
              type: string
              description: Device model
            osVersion:
              type: string
            appVersion:
              type: string
        refreshToken:
          type: string
          description: Active refresh token to resume an existing device session (200 with a null refreshToken). Omit for a new device.
    UserProfileResponse:
      type: object
      description: Full user profile with aggregated stats
      properties:
        user:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
              nullable: true
              description: Display name
            email:
              type: string
              format: email
              nullable: true
              description: Email if linked, null for anonymous
            authProvider:
              type: string
              enum:
              - anonymous
              - email
              description: Authentication method
            deviceInfo:
              type: object
              nullable: true
              description: Device platform/model info
            createdAt:
              type: string
              format: date-time
            memberSince:
              type: string
              format: date-time
              description: When the user started using the app
            lastUsedAt:
              type: string
              format: date-time
              nullable: true
        stats:
          type: object
          properties:
            totalBookmarks:
              type: integer
            totalFolders:
              type: integer
            totalFolderItems:
              type: integer
            daysSinceCreation:
              type: integer
    UpdateProfileRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Display name (1–100 characters)
    LinkEmailRequest:
      type: object
      required:
      - email
      - password
      properties:
        email:
          type: string
          format: email
          description: Email address to link
        password:
          type: string
          minLength: 6
          description: Password (min 6 characters)
        name:
          type: string
          description: Optional display name (defaults to email prefix)
    RevokeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Anonymous device access token from POST /v1/auth/anonymous