DPF Authentication API

openapi: 3.2.0
info:
  title: DPF Authentication API
  version: 1.1.0
  description: '## Common error responses


    Unless otherwise noted, any authenticated endpoint may also return the following

    responses, each with the standard `ErrorResponse` body. To avoid repetition they are

    not listed individually on each operation:


    - **400 Bad Request** — malformed JSON, unknown action, or missing/invalid fields

    - **401 Unauthorized** — missing or invalid JWT bearer token

    - **402 Payment Required** — the account has insufficient credits or an inactive subscription

    - **403 Forbidden** — authenticated but not permitted (no access to the resource, or a higher access level / plan tier is required)


    Operation-specific responses (e.g. `404`, `409`) are documented on each endpoint.'
  contact:
    name: Contact DPF
    url: mailto:contact@dpf-it.com
  license:
    name: Proprietary
    url: https://dpf-it.com/#terms
servers:
- url: https://api.dpf-it.com
  description: Production API
security: []
tags:
- name: Authentication
  description: User authentication and registration endpoints
paths:
  /auth/register:
    post:
      tags:
      - Authentication
      summary: Register new user
      description: Create a new user account
      operationId: registerUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '409':
          description: Email already registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/verify-otp:
    post:
      tags:
      - Authentication
      summary: Verify email with OTP
      description: Verify user email address using OTP sent to their email
      operationId: verifyOtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOtpRequest'
      responses:
        '200':
          description: Email verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyOtpResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/resend-otp:
    post:
      tags:
      - Authentication
      summary: Resend verification OTP
      description: Resend the registration verification code to an unverified account. Always returns a generic success message so the endpoint does not reveal whether an account exists.
      operationId: resendOtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address of the unverified account
                  example: user@example.com
      responses:
        '200':
          description: Generic acknowledgement (sent if an unverified account exists)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: If an unverified account exists for this email, a new code has been sent.
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/login:
    post:
      tags:
      - Authentication
      summary: User login
      description: Authenticate user and get JWT token
      operationId: loginUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/refresh:
    post:
      tags:
      - Authentication
      summary: Refresh an access token
      description: 'Exchange a refresh token for a new access token + refresh token pair. The presented refresh

        token is rotated (invalidated on use) — reuse of an already-rotated token revokes the entire

        token family, forcing re-login. No PKCE/redirect dance needed; this is the first-party

        equivalent of the OAuth 2.1 Authorization Server''s `grant_type=refresh_token` for the DPF web

        frontend, sharing the same underlying token store.'
      operationId: refreshToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '401':
          description: Refresh token is unknown, expired, or was already used (token family revoked)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: INVALID_EMAIL
            message:
              type: string
              description: Human-readable error message
              example: Invalid email format
    VerifyOtpResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            message:
              type: string
              example: Email verified successfully
    RegisterResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            userId:
              type: string
              format: uuid
              description: Unique user identifier
              example: 550e8400-e29b-41d4-a716-446655440000
            email:
              type: string
              format: email
              example: user@example.com
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
            createdAt:
              type: string
              format: date-time
              example: '2026-05-31T12:34:56Z'
    RefreshTokenRequest:
      type: object
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
          description: Refresh token previously issued by /auth/login or a prior /auth/refresh call
    VerifyOtpRequest:
      type: object
      required:
      - email
      - otp
      properties:
        email:
          type: string
          format: email
          description: Email address the account was registered with
          example: user@example.com
        otp:
          type: string
          description: One-time password from email (6 digits)
          example: '123456'
          pattern: ^\d{6}$
    RegisterRequest:
      type: object
      required:
      - email
      - password
      - firstName
      - lastName
      - termsAccepted
      properties:
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
          maxLength: 255
        password:
          type: string
          description: User password (min 8 chars, max 128 chars)
          example: SecurePassword123
          minLength: 8
          maxLength: 128
        firstName:
          type: string
          description: User first name
          example: John
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          description: User last name
          example: Doe
          minLength: 1
          maxLength: 100
        termsAccepted:
          type: boolean
          description: Affirmative acceptance of the Terms of Service and Privacy Policy. Must be true; registration is rejected (TERMS_NOT_ACCEPTED, 400) otherwise. The acceptance timestamp and document version are recorded on the user account.
          example: true
    RefreshTokenResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Same shape as LoginResponse.data, with a freshly-rotated token and refreshToken
    LoginRequest:
      type: object
      required:
      - email
      - password
      properties:
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
        password:
          type: string
          description: User password
          example: SecurePassword123
    LoginResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            userId:
              type: string
              format: uuid
              description: User unique identifier
              example: 550e8400-e29b-41d4-a716-446655440000
            email:
              type: string
              format: email
              description: User email address
              example: user@example.com
            firstName:
              type: string
              description: User first name
              example: John
            lastName:
              type: string
              description: User last name
              example: Doe
            token:
              type: string
              description: JWT access token for authentication (24h expiry)
              example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
            refreshToken:
              type: string
              description: 'Opaque refresh token (~90-day sliding window). Exchange it at `/auth/refresh` for a

                new access token once the current one expires — rotates on every use, so store the

                returned refreshToken and discard the old one each time.

                '
              example: q8c-BbPEpIF7ai-FrYUZ_a4acEk7finhMGHQ5vUvBvg
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login or registration