Ditto Audio Auth API

openapi: 3.2.0
info:
  title: ditto.audio Auth API
  description: Cloud API behind ditto.audio. The reader (reader.ditto.audio) and the voice studio (studio.ditto.audio) are separate apps sharing this one backend — see /docs/reader and /docs/inference for each app’s public surface. Third-party integrations want /docs/public (rendered for humans at https://ditto.audio/docs).
  version: '1.0'
  contact: {}
servers: []
tags:
- name: Auth
  description: Sign up, sign in (email + Google), email verification & password reset
paths:
  /v1/auth/config:
    get:
      operationId: AuthController_authConfig
      parameters: []
      responses:
        '200':
          description: ''
      summary: Public auth config (Google OAuth client IDs) the native apps fetch to drive…
      tags:
      - Auth
  /v1/auth/register:
    post:
      operationId: AuthController_register
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDto'
      responses:
        '201':
          description: Account created; confirmation email sent
        '409':
          description: Email already exists
      summary: Register; emails a confirmation link (no session until confirmed)
      tags:
      - Auth
  /v1/auth/login:
    post:
      operationId: AuthController_login
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginDto'
      responses:
        '200':
          description: JWT returned + cookie set
        '401':
          description: Invalid credentials
        '403':
          description: 'Email not verified (code: EMAIL_NOT_VERIFIED)'
      summary: Login; sets the shared .ditto.audio session cookie
      tags:
      - Auth
  /v1/auth/google:
    post:
      operationId: AuthController_google
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAuthDto'
      responses:
        '200':
          description: JWT returned + cookie set (account created if new)
        '401':
          description: Invalid or unverified Google credential
      summary: Sign in with a Google ID token (the phones' native flows); sets the shared…
      tags:
      - Auth
  /v1/auth/google/code:
    post:
      operationId: AuthController_googleCode
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleCodeAuthDto'
      responses:
        '200':
          description: JWT returned + cookie set (account created if new)
        '400':
          description: Redirect URI is not one of ours
        '401':
          description: Code refused by Google, nonce mismatch, or unverified email
        '503':
          description: Google sign-in is not configured (no client secret)
      summary: 'Finish the web''s "Continue with Google" redirect: exchange the code (PKCE)…'
      tags:
      - Auth
  /v1/auth/device/start:
    post:
      operationId: AuthController_deviceStart
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceStartDto'
      responses:
        '200':
          description: ''
      summary: Begin a device-link sign-in; returns a public linkToken + a secret deviceCode
      tags:
      - Auth
  /v1/auth/device/info:
    get:
      operationId: AuthController_deviceInfo
      parameters:
      - name: t
        required: true
        in: query
        schema:
          type: string
      responses:
        '404':
          description: Link expired or unknown
      summary: What a pending device-link says it is (shown on the /link page before Allow)
      tags:
      - Auth
  /v1/auth/device/approve:
    post:
      operationId: AuthController_deviceApprove
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceApproveDto'
      responses:
        '404':
          description: Link expired or unknown
      security:
      - bearer: []
      summary: Approve a device-link from the signed-in browser (binds the link to the current…
      tags:
      - Auth
  /v1/auth/device/redeem:
    post:
      operationId: AuthController_deviceRedeem
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceRedeemDto'
      responses:
        '410':
          description: Link expired
      summary: App polls with its deviceCode; returns {status:pending} or a session once…
      tags:
      - Auth
  /v1/auth/verify-email:
    post:
      operationId: AuthController_verifyEmail
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailDto'
      responses:
        '200':
          description: Email confirmed; JWT returned + cookie set
        '400':
          description: Invalid or expired token
      summary: Confirm an email from a verification link; signs the user in
      tags:
      - Auth
  /v1/auth/resend-verification:
    post:
      operationId: AuthController_resendVerification
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailDto'
      responses:
        '200':
          description: ''
      summary: Resend the email-confirmation link (always 200)
      tags:
      - Auth
  /v1/auth/password-reset/request:
    post:
      operationId: AuthController_requestPasswordReset
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailDto'
      responses:
        '200':
          description: ''
      summary: Email a password-reset link (always 200, no account enumeration)
      tags:
      - Auth
  /v1/auth/password-reset:
    post:
      operationId: AuthController_resetPassword
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordDto'
      responses:
        '200':
          description: Password updated
        '400':
          description: Invalid or expired token
      summary: Set a new password from a reset link
      tags:
      - Auth
  /v1/auth/refresh:
    post:
      operationId: AuthController_refresh
      parameters: []
      responses:
        '200':
          description: New accessToken issued
        '401':
          description: Session missing or already expired — sign in again
      security:
      - bearer: []
      summary: Renew the current session (sliding expiry) — returns a fresh JWT + cookie
      tags:
      - Auth
  /v1/auth/logout:
    post:
      operationId: AuthController_logout
      parameters: []
      responses:
        '200':
          description: ''
      summary: Clear the shared session cookie
      tags:
      - Auth
components:
  schemas:
    VerifyEmailDto:
      type: object
      properties:
        token:
          type: string
          description: Token from the verification email link
      required:
      - token
    LoginDto:
      type: object
      properties:
        email:
          type: string
          example: joe@ditto.audio
        password:
          type: string
          example: supersecure123
      required:
      - email
      - password
    EmailDto:
      type: object
      properties:
        email:
          type: string
          example: joe@ditto.audio
      required:
      - email
    DeviceStartDto:
      type: object
      properties: {}
    ResetPasswordDto:
      type: object
      properties:
        token:
          type: string
          description: Token from the password-reset email link
        password:
          type: string
          example: mynewsecret123
          minLength: 8
      required:
      - token
      - password
    GoogleAuthDto:
      type: object
      properties:
        credential:
          type: string
          description: Google ID token (JWT) from a native sign-in
      required:
      - credential
    DeviceRedeemDto:
      type: object
      properties: {}
    DeviceApproveDto:
      type: object
      properties: {}
    GoogleCodeAuthDto:
      type: object
      properties:
        code:
          type: string
          description: Authorization code from the redirect
        codeVerifier:
          type: string
          description: 'PKCE code_verifier (RFC 7636: 43-128 unreserved characters)'
        redirectUri:
          type: string
          description: The redirect_uri the authorization request used
        nonce:
          type: string
          description: The nonce the authorization request carried; must come back in the ID token
      required:
      - code
      - codeVerifier
      - redirectUri
      - nonce
    RegisterDto:
      type: object
      properties:
        email:
          type: string
          example: joe@ditto.audio
        password:
          type: string
          example: supersecure123
          minLength: 8
        name:
          type: string
          example: Joe Viscardi
      required:
      - email
      - password
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: ditto_sk_live_… API key, ditto_oat_… OAuth access token, or a session JWT
      type: http
      description: An API key (`ditto_sk_live_…`, made at https://ditto.audio/account/api-keys) authenticates /v1/audio/* and /v1/reader/*; an OAuth connection's one-hour access token (`ditto_oat_…`) holds the audio:read and audio:speech scopes only. Account routes (/v1/api-keys, /v1/usage, /v1/subscription) take the signed-in session's token (a JWT) only.