Rentberry Auth API

openapi: 3.2.0
info:
  title: Rentberry Auth API
  description: Renting Done Right. Finally.
  version: 4
tags:
- name: Auth
  description: Auth
paths:
  /v{version}/auth:
    get:
      tags:
      - Auth
      summary: Get current user session information
      description: Available since API version 2. Retrieves authenticated user session information including notifications counters.
      operationId: get_api_v2_auth_session
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Returns user session data
          content:
            application/json:
              schema:
                properties:
                  auth:
                    description: Authentication status
                    type: boolean
                  counters:
                    description: Notification counters
                    properties:
                      messagesTenant:
                        description: Count of unread messages for tenant
                        type: integer
                      messagesHomeowner:
                        description: Count of unread messages for homeowner
                        type: integer
                      propertiesHomeowner:
                        description: Combined count of applications, contracts and expired properties
                        type: integer
                      screeningCounter:
                        description: Count of unread screening notifications
                        type: integer
                      propertiesTenant:
                        description: Combined count for signatures, contracts and applications
                        type: integer
                      openHousesApplies:
                        description: Count of open house applications
                        type: integer
                      placeCounter:
                        description: Count of signatures and contracts notifications
                        type: integer
                      appliesCounter:
                        description: Count of application notifications
                        type: integer
                      emailVerified:
                        description: Flag indicating if email needs verification (1 = not verified)
                        type: integer
                      csMyCampaigns:
                        description: Count of campaign notifications
                        type: integer
                      csReceived:
                        description: Count of received notifications
                        type: integer
                      csSupported:
                        description: Count of support notifications
                        type: integer
                    type: object
                  user:
                    $ref: '#/components/schemas/UserAuthResponseV3'
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
      security:
      - XAuthToken: []
  /v{version}/auth/counters:
    get:
      tags:
      - Auth
      summary: Get user notification counters
      description: Available since API version 4. Retrieves counts of various notification types for the authenticated user.
      operationId: get_api_v4_notifications_counters
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Returns notification counters
          content:
            application/json:
              schema:
                properties:
                  messagesTenant:
                    description: Count of unread messages for tenant role
                    type: integer
                  messagesHomeowner:
                    description: Count of unread messages for homeowner role
                    type: integer
                  propertiesHomeowner:
                    description: Count of property-related notifications for homeowner
                    type: integer
                  screeningCounter:
                    description: Count of unread screening completion notifications
                    type: integer
                  propertiesTenant:
                    description: Count of property-related notifications for tenant
                    type: integer
                  openHousesApplies:
                    description: Count of open house applications
                    type: integer
                  placeCounter:
                    description: Count of new signatures and unviewed contracts
                    type: integer
                  appliesCounter:
                    description: Count of application notifications
                    type: integer
                  emailVerified:
                    description: Flag indicating if email needs verification (1 = not verified)
                    type: integer
                  rentalPaymentsTenant:
                    description: DEPRECATED - Count of rental payment notifications for tenant
                    type: integer
                  paymentsTenant:
                    description: Count of payment expiration notifications for tenant
                    type: integer
                  paymentsHomeowner:
                    description: Count of payment notifications for homeowner
                    type: integer
                  rentalPaymentsLandlord:
                    description: DEPRECATED - Count of rental payment notifications for landlord
                    type: integer
                  csMyCampaigns:
                    description: Count of campaign notifications
                    type: integer
                  csReceived:
                    description: Count of received notifications
                    type: integer
                  csSupported:
                    description: Count of support notifications
                    type: integer
                type: object
        '401':
          description: Unauthorized - User is not authenticated
        '403':
          description: Forbidden - User does not have sufficient permissions
      security:
      - XAuthToken: []
  /v{version}/auth/password:
    post:
      tags:
      - Auth
      summary: Request password reset
      description: Available since API version 1.
      operationId: post_api_v1_auth_password_restore
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - username
              properties:
                username:
                  description: User email address
                  type: string
                  format: email
              type: object
      responses:
        '200':
          description: Password reset email sent successfully
        '400':
          description: Invalid email format
  /v{version}/auth/register:
    post:
      tags:
      - Auth
      summary: Register a new user
      description: Available since API version 3.
      operationId: post_api_v3_auth_register
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - username
              - password
              - nameFirst
              - nameLast
              properties:
                username:
                  type: string
                  format: email
                password:
                  type: string
                nameFirst:
                  type: string
                nameLast:
                  type: string
                oauthConnectId:
                  type: string
                oauthProvider:
                  type: string
                recaptchaResponse:
                  type: string
                isRaiUser:
                  description: Mark user as RAI user (only sets to true, never resets)
                  type: boolean
              type: object
      responses:
        '200':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User2'
        '400':
          description: Validation failed
        '429':
          description: Rate limit exceeded
        '1004':
          description: User already registered
        '1005':
          description: User blocked
  /v{version}/auth/token:
    post:
      tags:
      - Auth
      summary: Authenticate user and get token
      description: Available since API version 1.
      operationId: post_api_v1_auth_token
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - username
              - plainPassword
              properties:
                username:
                  type: string
                  format: email
                plainPassword:
                  type: string
                oauthConnectId:
                  type: string
                oauthProvider:
                  type: string
                isRaiUser:
                  description: Mark user as RAI user (only sets to true, never resets)
                  type: boolean
              type: object
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                properties:
                  auth_token:
                    type: string
                type: object
        '400':
          description: Validation failed
        '401':
          description: Authentication failed
        '1005':
          description: User blocked or not verified
  /v{version}/auth/email-otp/request:
    post:
      tags:
      - Auth
      summary: Request OTP code for email authentication
      description: Sends a 4-digit OTP code to the specified email address for passwordless login or registration.
      operationId: post_api_v1_auth_email_otp_request
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
              type: object
      responses:
        '200':
          description: OTP code sent (same response regardless of email existence)
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: OK
                type: object
        '400':
          description: Validation failed
        '429':
          description: Rate limit exceeded
  /v{version}/auth/email-otp/verify:
    post:
      tags:
      - Auth
      summary: Verify OTP code and login or register
      description: Verifies the 4-digit OTP code. If user exists - logs in, if not - creates a new account.
      operationId: post_api_v1_auth_email_otp_verify
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - email
              - code
              properties:
                email:
                  type: string
                  format: email
                code:
                  type: integer
                  maximum: 9999
                  minimum: 1000
                nameFirst:
                  description: Optional, used for registration
                  type: string
                nameLast:
                  description: Optional, used for registration
                  type: string
                isRaiUser:
                  description: Mark user as RAI user (only sets to true, never resets)
                  type: boolean
              type: object
      responses:
        '200':
          description: Login or registration successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAuthResponse'
        '400':
          description: Invalid or expired code
  /v{version}/oauth/{provider}:
    get:
      tags:
      - Auth
      summary: Get OAuth authorization URL
      description: Available since API version 1. Returns the URL to initiate OAuth authorization with the specified provider.
      operationId: get_api_v1_oauth_init
      parameters:
      - name: provider
        in: path
        description: OAuth provider name (e.g., "google", "apple")
        required: true
        schema:
          type: string
          pattern: google|google\.ios|apple|apple\.app|apple\.rai
          enum:
          - google
          - apple
      - name: redirectUrl
        in: query
        description: URL to redirect after OAuth authentication
        schema:
          type: string
      - name: authActionType
        in: query
        description: Type of authentication action (e.g., "login", "register", "connect")
        schema:
          type: string
          enum:
          - login
          - register
          - connect
      - name: prevUrl
        in: query
        description: Previous URL to return to after authentication
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: OAuth authorization URL successfully generated
          content:
            application/json:
              schema:
                properties:
                  oauthUrl:
                    description: URL to redirect the user to for OAuth authorization
                    type: string
                type: object
        '400':
          description: Invalid provider or parameters
        '429':
          description: Rate limit exceeded
  /v{version}/oauth/apple/callback:
    post:
      tags:
      - Auth
      summary: Handle Apple OAuth callback
      description: Available since API version 4. Processes the callback from Apple OAuth authentication and redirects to the authentication page.
      operationId: post_api_v4_oauth_apple_callback
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        description: Apple callback data
        content:
          application/json:
            schema:
              properties:
                code:
                  description: Authorization code from Apple
                  type: string
                state:
                  description: State parameter for CSRF protection
                  type: string
                id_token:
                  description: JWT ID token from Apple
                  type: string
                user:
                  description: User information from Apple (JSON string)
                  type: string
                error:
                  description: Error message if authentication failed
                  type: string
              type: object
      responses:
        '302':
          description: Redirect to authentication page
          headers:
            Location:
              description: URL to redirect to
              schema:
                type: string
        '400':
          description: Invalid callback data
        '429':
          description: Rate limit exceeded
  /v{version}/oauth/{provider}/authorize/code:
    get:
      tags:
      - Auth
      summary: Authorize via OAuth code
      description: Available since API version 2. Processes OAuth authorization code from any supported provider.
      operationId: get_api_v1_oauth_authorize
      parameters:
      - name: provider
        in: path
        description: OAuth provider name
        required: true
        schema:
          type: string
          pattern: google|google\.ios|apple|apple\.app|apple\.rai
          enum:
          - google
          - apple
      - name: code
        in: query
        description: Authorization code from the provider
        required: true
        schema:
          type: string
      - name: authActionType
        in: query
        description: Type of authentication action (login, register, connect)
        schema:
          type: string
          enum:
          - login
          - register
          - connect
      - name: isRaiUser
        in: query
        description: Mark user as RAI user. Pass "1" or "true" to set. Only sets to true, never resets.
        schema:
          type: string
          enum:
          - '0'
          - '1'
          - 'true'
          - 'false'
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Authorization successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthUserResponse'
        '400':
          description: No OAuth code provided
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
              example:
                error: No OAuth code provided
        '401':
          description: Authorization failed
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
              example:
                error: Invalid OAuth code
        '429':
          description: Rate limit exceeded
  /v{version}/oauth/google/authorize/token:
    post:
      tags:
      - Auth
      summary: Verify Google One Tap token
      description: Available since API version 4. Verifies and processes a Google One Tap authentication token.
      operationId: post_api_v4_google_one_tap
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - token
              properties:
                token:
                  description: Google One Tap JWT token
                  type: string
                authActionType:
                  description: Type of authentication action (login, register, connect)
                  type: string
                isRaiUser:
                  description: Mark user as RAI user (only sets to true, never resets)
                  type: boolean
                provider:
                  description: Google provider variant (google, google.ios). Defaults to google.
                  type: string
                  enum:
                  - google
                  - google.ios
              type: object
      responses:
        '200':
          description: Token verification successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthUserResponse'
        '401':
          description: Token verification failed
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
        '429':
          description: Rate limit exceeded
  /v{version}/oauth/{provider}/authorize/access-token:
    get:
      tags:
      - Auth
      summary: Authorize via OAuth access token
      description: Available since API version 2. Processes OAuth short-lived access token from any supported provider.
      operationId: get_api_v1_oauth_authorize_by_short_lived_access_token
      parameters:
      - name: provider
        in: path
        description: OAuth provider name
        required: true
        schema:
          type: string
          pattern: google|google\.ios|apple|apple\.app|apple\.rai
          enum:
          - google
          - apple
      - name: code
        in: query
        description: Short-lived access token from the provider
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Authentication action type
        schema:
          type: string
      - name: isRaiUser
        in: query
        description: Mark user as RAI user. Pass "1" or "true" to set. Only sets to true, never resets.
        schema:
          type: string
          enum:
          - '0'
          - '1'
          - 'true'
          - 'false'
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Authorization successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthUserResponse'
        '400':
          description: No OAuth code provided
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
        '401':
          description: Authorization failed
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
        '429':
          description: Rate limit exceeded
  /v{version}/oauth/disconnect/{provider}:
    delete:
      tags:
      - Auth
      summary: Disconnect OAuth provider
      description: Available since API version 1. Removes the connection between user account and OAuth provider.
      operationId: delete_api_v1_oauth_authorize_disconnect_user
      parameters:
      - name: provider
        in: path
        description: OAuth provider ID to disconnect
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Provider disconnected successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: No connected user for this provider
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
        '403':
          description: Trying to disconnect provider that belongs to another user
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
        '401':
          description: Unauthorized - User is not authenticated
        '404':
          description: Provider not found
      security:
      - XAuthToken: []
components:
  schemas:
    union: []
    UserOauthProvider:
      properties:
        id:
          type: integer
        provider:
          type: string
        providerId:
          type: string
        connectId:
          type: string
        nameFirst:
          type: string
        nameLast:
          type: string
        pictureUrl:
          type: string
        appId:
          type: string
      type: object
    OAuthUserResponse:
      properties:
        userData:
          $ref: '#/components/schemas/OAuthUserUser'
        action:
          type: string
        accessToken:
          type: string
        oauthProvider:
          type: string
        oauthConnectId:
          type: string
      type: object
    UserAddress2:
      required:
      - street
      - houseNumber
      - city
      - zip
      properties:
        street:
          type: string
          maxLength: 255
          minLength: 1
        houseNumber:
          type: string
          maxLength: 255
          minLength: 1
        streetType:
          type:
          - string
          - 'null'
          maxLength: 10
        city:
          type: string
          maxLength: 255
          minLength: 3
        state:
          $ref: '#/components/schemas/State2'
        zip:
          type: string
          maxLength: 9
          minLength: 5
      type: object
    UserCreditScore:
      properties:
        score:
          type: integer
        creditScoreUpdatedAt:
          type: string
          format: date-time
        alert:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    RentalPaymentAccount:
      properties:
        stripeAccountId:
          type: string
        isStripeOnboardingFinished:
          type: boolean
          default: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    UserAuthResponseV3:
      required:
      - nameFirst
      - nameLast
      - username
      - phone
      - birthday
      properties:
        hasPassword:
          type: boolean
        phoneCountryCode:
          type: string
        id:
          type: integer
        nameFirst:
          type: string
          maxLength: 255
          minLength: 2
        nameMiddle:
          type: string
          maxLength: 255
          minLength: 1
        nameLast:
          type: string
          maxLength: 255
          minLength: 2
        company:
          $ref: '#/components/schemas/Company'
        companyName:
          type: string
          maxLength: 255
          minLength: 1
        username:
          type: string
          maxLength: 255
          minLength: 1
        profilePictureThumbs:
          type: string
        phone:
          type: string
          maxLength: 15
          minLength: 7
        birthday:
          type: string
          format: date-time
        bio:
          type: string
          maxLength: 1500
        oauthProviders:
          type: array
          items:
            $ref: '#/components/schemas/UserOauthProvider'
        address:
          $ref: '#/components/schemas/UserAddress2'
        creditScore:
          $ref: '#/components/schemas/UserCreditScore'
        criminalReport:
          $ref: '#/components/schemas/UserCriminalReport'
        stripeCustomer:
          $ref: '#/components/schemas/UserStripeCustomer2'
        active:
          type: boolean
          default: true
        fromNotBerryForbiddenCountry:
          type: boolean
          default: false
        verified:
          type: boolean
          default: false
        emailVerified:
          type: boolean
          default: false
        phoneVerified:
          type: boolean
          default: false
        registered:
          type: boolean
          default: true
        emailNotVerifiedAfter:
          type: string
          format: date-time
        lastActiveAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        statusType:
          type: string
          default: regular
          enum:
          - regular
          - premium
          - premium_pending
          - vip
          - vip_pending
        authToken:
          type: string
        deleted:
          type: boolean
          default: false
        rentalPaymentAccount:
          $ref: '#/components/schemas/RentalPaymentAccount'
        newsletterSubscription:
          type: boolean
          default: false
        premiumPartner:
          type: boolean
          default: false
        locale:
          type: string
          default: en_US
          enum:
          - en_US
          - es_ES
        currency:
          type: string
        lengthUnit:
          type: string
          enum:
          - m
          - ft
        isRaiUser:
          type: boolean
          default: false
        intercomSecret:
          type: string
      type: object
    UserStripeCustomer2:
      properties:
        customerId:
          type: string
        user:
          $ref: '#/components/schemas/User2'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    OAuthUserUser:
      properties:
        id:
          type: integer
        nameFirst:
          type: string
        nameLast:
          type: string
        username:
          type: string
        phone:
          type: string
        pictureUrl:
          type: string
      type: object
    State2:
      properties:
        id:
          type: integer
        shortName:
          type:
          - string
          - 'null'
          default: null
          maxLength: 200
          minLength: 1
        name:
          type:
          - string
          - 'null'
          default: null
          maxLength: 255
          minLength: 1
      type: object
    UserAuthResponse:
      properties:
        id:
          type: integer
        hasPassword:
          type: boolean
        locale:
          type: string
        nameFirst:
          type: string
        nameMiddle:
          type: string
        nameLast:
          type: string
        companyName:
          type: string
        username:
          type: string
        statusType:
          type: string
        phone:
          type: integer
        birthday:
          type: string
          format: date-time
        bio:
          type: string
        fromNotBerryForbiddenCountry:
          type: boolean
        active:
          type: boolean
        verified:
          type: boolean
        emailVerified:
          type: boolean
        phoneVerified:
          type: boolean
        registered:
          type: boolean
        emailNotVerifiedAfter:
          type: string
          format: date-time
        lastActiveAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        authToken:
          type: string
        phoneCountryCode:
          $ref: '#/components/schemas/union'
        roles:
          $ref: '#/components/schemas/union'
        currency:
          type: string
        lengthUnit:
          type: string
        profilePictureThumbs:
          type: string
        rentalPaymentAccount:
          $ref: '#/components/schemas/RentalPaymentAccount'
        intercomSecret:
          type: string
      type: object
    User2:
      required:
      - nameFirst
      - nameLast
      - username
      - phone
      - birthday
      properties:
        hasPassword:
          type: boolean
        phoneCountryCode:
          type: string
        id:
          type: integer
        nameFirst:
          type: string
          maxLength: 255
          minLength: 2
        nameMiddle:
          type: string
          maxLength: 255
          minLength: 1
        nameLast:
          type: string
          maxLength: 255
          minLength: 2
        company:
          $ref: '#/components/schemas/Company'
        companyName:
          type: string
          maxLength: 255
          minLength: 1
        username:
          type: string
          maxLength: 255
          minLength: 1
        profilePictureThumbs:
          type: string
        phone:
          type: string
          maxLength: 15
          minLength: 7
        birthday:
          type: string
          format: date-time
        bio:
          type: string
          maxLength: 1500
        oauthProviders:


# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/openapi/rentberry-auth-api-openapi.yml