Autoposting.ai Auth API

openapi: 3.2.0
info:
  title: Autoposting Auth API
  description: 'Schedule, publish, and AI-enhance social content across X, LinkedIn, Instagram, Threads, and YouTube. All responses use the `{ "success": boolean, "data": ... }` envelope. Authenticate with an API key (`Authorization: Bearer sk-social-...` or `x-api-key: sk-social-...`).'
  version: 1.0.0
servers:
- url: https://app.autoposting.ai/api-proxy
  description: Production
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Auth
  description: Signup, login, logout, social login, profile management, email change, and session management.
paths:
  /auth/signup:
    post:
      operationId: signup
      summary: Sign up
      description: Create a new user account with email and password. Rate limited to 5 requests per IP per hour.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  description: User's email address.
                  example: user@example.com
                password:
                  type: string
                  description: Account password.
                  example: SecurePass123!
                name:
                  type: string
                  description: Display name for the user.
                  example: Jane Doe
      responses:
        '200':
          description: Account created.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/AuthSession'
  /auth/login:
    post:
      operationId: loginWithPassword
      summary: Log in
      description: Authenticate with email and password to receive a session token.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  description: User's email address.
                  example: user@example.com
                password:
                  type: string
                  description: Account password.
                  example: SecurePass123!
      responses:
        '200':
          description: Authenticated.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/AuthSession'
  /auth/logout:
    post:
      operationId: logout
      summary: Log out
      description: Invalidate the current session token.
      tags:
      - Auth
      responses:
        '200':
          description: Session ended.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    example: {}
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/verify-email:
    post:
      operationId: verifyEmailWithOtp
      summary: Verify email with OTP
      description: Verify an email address using the 6-digit OTP code sent to the email.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - code
              properties:
                email:
                  type: string
                  description: Email address to verify.
                  example: user@example.com
                code:
                  type: string
                  description: 6-digit OTP code sent to the email.
                  example: '123456'
      responses:
        '200':
          description: Email verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
    get:
      operationId: verifyEmailWithToken
      summary: Verify email via token link
      description: Verify an email address via the token link sent to the user. Used by the email verification link.
      tags:
      - Auth
      parameters:
      - name: token
        in: query
        required: true
        description: Verification token from the email link.
        schema:
          type: string
      responses:
        '200':
          description: Email verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
  /verify-email:
    get:
      operationId: verifyEmailWithTokenAlias
      summary: Verify email via token link (alias)
      description: Backward-compatible alias for token-based email verification.
      tags:
      - Auth
      parameters:
      - name: token
        in: query
        required: true
        description: Verification token from the email link.
        schema:
          type: string
      responses:
        '200':
          description: Email verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
  /auth/resend-verification:
    post:
      operationId: resendVerification
      summary: Resend verification email
      description: Resend the verification email to the given address.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  description: Email address to resend verification to.
                  example: user@example.com
      responses:
        '200':
          description: Verification email sent.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
  /auth/forgot-password:
    post:
      operationId: forgotPassword
      summary: Request password reset
      description: Request a password reset email for the given address.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  description: Email address to send the reset link to.
                  example: user@example.com
      responses:
        '200':
          description: Reset email sent.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
  /auth/reset-password:
    post:
      operationId: resetPassword
      summary: Reset password
      description: Reset the account password using a token from the reset email link.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              - password
              properties:
                token:
                  type: string
                  description: Reset token from the email link.
                password:
                  type: string
                  description: New password.
                  example: SecurePass123!
      responses:
        '200':
          description: Password reset.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
  /auth/change-password:
    post:
      operationId: changePassword
      summary: Change password
      description: Change the password for the authenticated account.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - currentPassword
              - newPassword
              properties:
                currentPassword:
                  type: string
                  description: Current account password.
                newPassword:
                  type: string
                  description: New password.
      responses:
        '200':
          description: Password changed.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/social/{provider}:
    get:
      operationId: initiateSocialLogin
      summary: Initiate social OAuth
      description: Redirect the user to this URL to begin the OAuth flow for the given provider.
      tags:
      - Auth
      parameters:
      - name: provider
        in: path
        required: true
        description: OAuth provider.
        schema:
          type: string
          enum:
          - google
          - github
          example: google
      responses:
        '200':
          description: OAuth flow initiated.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
  /auth/social/exchange:
    post:
      operationId: exchangeSocialCode
      summary: Exchange OAuth code
      description: Exchange an OAuth authorization code for a session token.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              - code
              properties:
                provider:
                  type: string
                  description: 'OAuth provider: google or github.'
                  enum:
                  - google
                  - github
                  example: google
                code:
                  type: string
                  description: Authorization code from the OAuth redirect.
      responses:
        '200':
          description: Session created.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/AuthSession'
  /auth/social/complete:
    post:
      operationId: completeSocialLogin
      summary: Complete social login
      description: Complete a social login or link a social account to the authenticated account.
      tags:
      - Auth
      responses:
        '200':
          description: Social account linked.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/profile:
    get:
      operationId: getProfile
      summary: Get current user profile
      description: Get the profile of the currently authenticated user.
      tags:
      - Auth
      responses:
        '200':
          description: Current user profile.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/UserProfile'
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
    patch:
      operationId: updateProfile
      summary: Update user profile
      description: Update the authenticated user's profile fields.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name.
                  example: Jane Doe
                avatarUrl:
                  type: string
                  description: URL to the user's avatar image.
                  example: https://cdn.example.com/avatar.jpg
      responses:
        '200':
          description: Profile updated.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/UserProfile'
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/email-change/initiate:
    post:
      operationId: initiateEmailChange
      summary: Initiate email change
      description: Start the email change flow. Sends an OTP to the current email address.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newEmail
              properties:
                newEmail:
                  type: string
                  description: The new email address to change to.
                  example: new@example.com
      responses:
        '200':
          description: OTP sent to current email.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/email-change/verify-current:
    post:
      operationId: verifyCurrentEmail
      summary: Verify current email OTP
      description: 'Step 2 of email change: verify the OTP sent to the current email address.'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: OTP sent to the current email.
                  example: '123456'
      responses:
        '200':
          description: Current email verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/email-change/verify-new:
    post:
      operationId: verifyNewEmail
      summary: Verify new email OTP
      description: 'Step 3 of email change: verify the OTP sent to the new email address.'
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: OTP sent to the new email address.
                  example: '123456'
      responses:
        '200':
          description: New email verified and applied.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/sessions:
    get:
      operationId: listSessions
      summary: List active sessions
      description: List the authenticated user's active sessions.
      tags:
      - Auth
      responses:
        '200':
          description: Active sessions.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/sessions/{id}:
    delete:
      operationId: revokeSession
      summary: Revoke a session
      description: Revoke a specific session by its ID.
      tags:
      - Auth
      parameters:
      - name: id
        in: path
        required: true
        description: Session ID to revoke.
        schema:
          type: string
          example: session_01
      responses:
        '200':
          description: Session revoked.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
  /auth/sessions/revoke-all:
    post:
      operationId: revokeAllSessions
      summary: Revoke all other sessions
      description: Invalidate all sessions except the current one.
      tags:
      - Auth
      responses:
        '200':
          description: Other sessions revoked.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
        '401':
          description: Missing or invalid session token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
components:
  schemas:
    AuthSession:
      type: object
      properties:
        token:
          type: string
          example: sk-social-your-key
        user:
          $ref: '#/components/schemas/AuthUser'
    Session:
      type: object
      properties:
        id:
          type: string
          example: session_01
        createdAt:
          type: string
          example: '2024-01-01T00:00:00Z'
        lastUsedAt:
          type: string
          example: '2024-01-10T12:00:00Z'
        userAgent:
          type: string
          example: Mozilla/5.0 ...
        isCurrent:
          type: boolean
          example: true
    AuthUser:
      type: object
      properties:
        id:
          type: string
          example: usr_01HXYZ
        email:
          type: string
          example: user@example.com
        name:
          type: string
          example: Jane Doe
        emailVerified:
          type: boolean
          example: true
    UserProfile:
      type: object
      properties:
        id:
          type: string
          example: usr_01HXYZ
        email:
          type: string
          example: user@example.com
        name:
          type: string
          example: Jane Doe
        avatarUrl:
          type: string
          example: https://cdn.example.com/avatar.jpg
        emailVerified:
          type: boolean
          example: true
        createdAt:
          type: string
          example: '2024-01-01T00:00:00Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key as `Authorization: Bearer sk-social-...`'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key as `x-api-key: sk-social-...`'