RentCheck O Auth2 API

openapi: 3.2.0
info:
  title: RentCheck REST O Auth2 API
  version: 1.0.0
  description: '## Mission

    At RentCheck, our mission is plain and simple: To make renting fair and transparent for everyone involved.'
  contact:
    name: RentCheck Support
    email: support@getrentcheck.com
servers:
- url: https://prod-public-api.getrentcheck.com
  description: Production server
security:
- bearerAuth: []
  x-app-id: []
  x-app-secret: []
tags:
- name: OAuth2
paths:
  /v1/oAuth2/access:
    post:
      x-internal: true
      summary: Grant OAuth2 access and redirect back to the integration
      tags:
      - OAuth2
      description: 'Fourth (and final) hop of the OAuth2 authorization-code flow used by

        integration apps (currently only the Zapier connector). The grant-access

        form rendered by the earlier steps posts here once the user confirms.

        The one-time authorization `code` is persisted against the

        user''s profile so that a subsequent

        `POST /v1/oAuth2/token` call from the integration can exchange it for

        an access + refresh token pair, and then issues a 302 redirect back to

        the integration''s `redirectUrl`.


        This endpoint does not require a bearer token.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - redirectUrl
              - code
              - uid
              properties:
                redirectUrl:
                  type: string
                  format: uri
                  description: The `redirect_uri` originally supplied to `GET /v1/oAuth2/authentication`; used as the 302 `Location` target with `code` and `state` appended.
                code:
                  type: string
                  description: The one-time authorization code generated by `GET /v1/oAuth2/authentication`, persisted on the user's profile so `POST /v1/oAuth2/token` can exchange it for a token pair.
                uid:
                  type: string
                  description: The RentCheck user id resolved earlier in the flow.
                orgId:
                  type: string
                  description: Optional RentCheck organisation id when the caller belongs to more than one org (Zapier only).
      responses:
        '302':
          description: 'Redirects back to the integration''s `redirectUrl`, with the OAuth

            `code` (and `state`) appended as query-string parameters, so the

            integration can complete the authorization-code exchange.

            '
          headers:
            Location:
              description: The `redirectUrl` supplied by the caller.
              schema:
                type: string
                format: uri
      operationId: postV1OAuth2Access
      x-operation-id-source: derived
  /v1/oAuth2/authentication:
    get:
      x-internal: true
      summary: Render the RentCheck OAuth2 login form
      tags:
      - OAuth2
      description: 'First hop of the OAuth2 authorization-code flow used by integration apps

        (currently only the Zapier connector). Returns an HTML login form the

        end user submits to prove their identity — the form''s action target is

        `POST /v1/oAuth2/validateUser`. The response `Content-Type` is

        `text/html`; nothing about this endpoint is JSON.


        This endpoint does not require a bearer token because it *is* the point

        where the user authenticates.'
      parameters:
      - in: query
        name: client_id
        required: true
        description: 'The RentCheck integration-app id. If it does not resolve to a

          registered app the endpoint responds with 401 `App not authorized

          or missing client_id`.

          '
        schema:
          type: string
      - in: query
        name: state
        required: true
        description: Opaque OAuth2 `state` value; echoed back verbatim on the redirect the login form will fire.
        schema:
          type: string
      - in: query
        name: redirect_uri
        required: true
        description: The callback URL to redirect to once the user has authenticated. Appended to the redirect URL as `<redirect_uri>?state=<state>&code=<code>`.
        schema:
          type: string
          format: uri
      responses:
        '200':
          description: Returns the login HTML page.
          content:
            text/html:
              schema:
                type: string
                description: The rendered login HTML page.
        '400':
          description: 'Bad request — one of the required query-string parameters is missing.

            The exact strings are listed below.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    enum:
                    - parameters are missing
                    - parameter state is required
                    - parameter redirect_uri is required
                    example: parameter state is required
        '401':
          description: 'Unauthorized — the `client_id` does not resolve to a registered

            integration app.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    enum:
                    - App not authorized or missing client_id
                    example: App not authorized or missing client_id
      operationId: getV1OAuth2Authentication
      x-operation-id-source: derived
  /v1/oAuth2/emailPasswordAuth:
    post:
      summary: Creates an access/refresh token pair
      tags:
      - OAuth2
      security:
      - x-app-id: []
        x-app-secret: []
      description: 'Exchanges an email + password for a fresh access/refresh token pair. The body must

        supply the caller''s `email` together with EITHER `password` (RentCheck account password)

        OR `integration_password` (the value obtained from the RentCheck API integrations page).

        Exactly one of the two credentials must be supplied.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/oauth2_email_password_auth_request_model'
      responses:
        '200':
          description: Returns the new tokens pair
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/oauth2_email_password_auth_response_model'
        '400':
          description: "Bad request — the request body failed validation. The validation error message\nis returned as `error`. Common cases:\n  - `\"data.email\" is required` — the `email` field is missing.\n  - `\"data\" must contain at least one of [password, integration_password]` —\n    neither credential was supplied.\n  - `\"data\" contains a conflict between exclusive peers [password, integration_password]` —\n    both credentials were supplied at once.\n  - `\"data.email\" must be a valid email` — malformed email address.\n"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    example: '"data.email" is required'
        '401':
          description: 'Unauthorized — the supplied credentials did not resolve to a RentCheck user.

            Both authentication paths (RentCheck account password and integration password)

            collapse every failure mode into a single generic error to avoid account

            enumeration.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    enum:
                    - invalid credentials
                    example: invalid credentials
      operationId: postV1OAuth2EmailPasswordAuth
      x-operation-id-source: derived
  /v1/oAuth2/me:
    post:
      x-internal: true
      summary: Identify the caller by their OAuth2 access token
      tags:
      - OAuth2
      description: 'Companion to `POST /v1/oAuth2/token`: given the access token issued by

        the token endpoint, returns the RentCheck user id, org id, and app id

        the token was scoped to, along with the current server time. Primarily

        consumed by the Zapier integration to render the connected account''s

        email in the UI.


        The endpoint reads the caller''s identity from the decoded access token;

        the request body is ignored.'
      responses:
        '200':
          description: Returns the caller's identity payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/oauth2_me_response_model'
        '401':
          description: 'Unauthorized — either a standard auth-token failure, or the userId

            decoded from the token no longer resolves to an active user, in which

            case the error is `Code not valid`.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    enum:
                    - token is not valid
                    - authorization header is empty
                    - authorization header is not valid
                    - 'format for Authorization must be: Bearer [token]'
                    - refresh token is not valid for resources
                    - not well-formed token
                    - Code not valid
                    example: Code not valid
      operationId: postV1OAuth2Me
      x-operation-id-source: derived
  /v1/oAuth2/refreshToken:
    post:
      summary: Refresh tokens
      tags:
      - OAuth2
      security: []
      description: 'Exchange a refresh token for a new access/refresh token pair. The endpoint is unauthenticated

        (no bearer token, app id, or app secret headers required); the supplied refresh token JWT is

        the only credential.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/oauth2_refresh_token_request_model'
      responses:
        '200':
          description: Returns the new tokens pair
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/oauth2_refresh_token_response_model'
        '401':
          description: Unauthorized — supplied refresh token failed validation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    enum:
                    - Invalid token
                    example: Invalid token
      operationId: postV1OAuth2RefreshToken
      x-operation-id-source: derived
  /v1/oAuth2/token:
    post:
      x-internal: true
      security: []
      summary: Exchange an OAuth2 authorization code for access + refresh tokens
      tags:
      - OAuth2
      description: 'Third leg of the RentCheck OAuth2 authorization-code flow — primarily

        used by the Zapier integration. The caller presents its integration

        `client_id` / `client_secret` alongside the one-time `code` issued to the

        RentCheck user during login, and receives a short-lived access token +

        long-lived refresh token in return.


        The `code` is single-use: it is cleared as soon as the exchange succeeds.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/oauth2_token_request_model'
      responses:
        '200':
          description: Returns the caller's fresh access + refresh tokens and their scoped org id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/oauth2_token_response_model'
        '401':
          description: 'Unauthorized — either the `client_id` / `client_secret` failed to

            validate against the RentCheck integration settings, or the supplied `code`

            did not resolve to a user (already-consumed / never-issued).

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    enum:
                    - App not valid
                    - Code not valid
                    example: Code not valid
      operationId: postV1OAuth2Token
      x-operation-id-source: derived
  /v1/oAuth2/validateOrg:
    post:
      x-internal: true
      summary: Confirm the organisation the OAuth2 code should be scoped to
      tags:
      - OAuth2
      description: 'Third hop of the OAuth2 authorization-code flow used by integration

        apps whose users belong to more than one RentCheck organisation

        (currently only Zapier). The org-selection form rendered by

        `POST /v1/oAuth2/validateUser` submits the selected org here. Response

        is HTML — nothing about this endpoint is JSON.


        This endpoint does not require a bearer token.


        Response flow:

        - `orgId` missing → re-renders the org-selection form with an inline

        `Please select a Team from the dropdown.` error (`HTTP 409`).

        - `orgId` present → renders the grant-access form (`HTTP 200`).'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - redirectUrl
              - code
              - uid
              properties:
                redirectUrl:
                  type: string
                  format: uri
                  description: The `redirect_uri` originally supplied to `GET /v1/oAuth2/authentication`.
                code:
                  type: string
                  description: The one-time authorization code generated by `GET /v1/oAuth2/authentication`.
                uid:
                  type: string
                  description: The RentCheck user id resolved by `POST /v1/oAuth2/validateUser`.
                orgId:
                  type: string
                  description: The RentCheck organisation id selected by the end user. Omitting or leaving this blank re-renders the selection form with an inline error.
                label:
                  type: string
                  description: Optional label displayed on the rendered form; forwarded verbatim from the caller.
      responses:
        '200':
          description: The user selected an org; renders the grant-access form.
          content:
            text/html:
              schema:
                type: string
                description: The rendered grant-access HTML form.
        '409':
          description: 'The org-selection form was submitted without an `orgId`. The form is

            re-rendered with an inline `Please select a Team from the dropdown.`

            error banner.

            '
          content:
            text/html:
              schema:
                type: string
                description: The rendered org-selection HTML form with the inline error banner.
      operationId: postV1OAuth2ValidateOrg
      x-operation-id-source: derived
  /v1/oAuth2/validateUser:
    post:
      x-internal: true
      summary: Validate user credentials during the OAuth2 login form submit
      tags:
      - OAuth2
      description: 'Second hop of the OAuth2 authorization-code flow used by integration

        apps (currently only the Zapier connector). The RentCheck login form

        rendered by `GET /v1/oAuth2/authentication` POSTs the user''s email and

        password here. Depending on the outcome the endpoint re-renders one of

        three HTML forms and returns HTML — nothing about this endpoint is JSON.


        This endpoint does not require a bearer token because it *is* the point

        where the user authenticates.


        Response flow:

        - Missing or invalid email/password → re-renders the login form with

        an inline error banner and `HTTP 409` status.

        - Valid credentials for a non-Zapier app, or a Zapier app whose user

        belongs to a single organisation → stores the OAuth code against

        the user and renders the grant-access form (`HTTP 200`).

        - Valid credentials for a Zapier app whose user belongs to multiple

        organisations → renders the org-selection form (`HTTP 200`).'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - redirectUrl
              - code
              - appId
              - email
              - password
              properties:
                redirectUrl:
                  type: string
                  format: uri
                  description: The `redirect_uri` originally supplied to `GET /v1/oAuth2/authentication`.
                code:
                  type: string
                  description: The one-time authorization code generated by `GET /v1/oAuth2/authentication`.
                appId:
                  type: string
                  description: RentCheck integration-app id (matches the `client_id` supplied to `GET /v1/oAuth2/authentication`).
                email:
                  type: string
                  format: email
                  description: End-user's RentCheck email address.
                password:
                  type: string
                  description: End-user's RentCheck integration password.
                label:
                  type: string
                  description: Optional label displayed on the rendered form; forwarded verbatim from the auth form.
      responses:
        '200':
          description: Renders either the grant-access form (single org / non-Zapier) or the org-selection form (multi-org Zapier caller).
          content:
            text/html:
              schema:
                type: string
                description: The rendered grant-access or org-selection HTML form.
        '409':
          description: 'Credentials failed validation. The login form is re-rendered with an

            inline error banner (`E-mail and password are required`, `Invalid

            e-mail`, or `Login failed`).

            '
          content:
            text/html:
              schema:
                type: string
                description: The rendered login HTML form with the inline error banner.
      operationId: postV1OAuth2ValidateUser
      x-operation-id-source: derived
components:
  schemas:
    oauth2_email_password_auth_response_model:
      type: object
      required:
      - access_token
      - refresh_token
      properties:
        access_token:
          type: string
          description: The access token is used to validate a request to the RentCheck API.
        refresh_token:
          type: string
          description: The refresh token is used to request a fresh access token.
    oauth2_refresh_token_response_model:
      type: object
      required:
      - access_token
      - refresh_token
      properties:
        access_token:
          type: string
          description: The access token is used to validate a request to the RentCheck API.
        refresh_token:
          type: string
          description: The refresh token is used to request a fresh access token.
    oauth2_token_response_model:
      x-internal: true
      type: object
      description: Successful token-exchange response for `POST /v1/oAuth2/token`.
      required:
      - access_token
      - refresh_token
      - org_id
      properties:
        access_token:
          type: string
          description: 'Short-lived bearer token to use as `Authorization: Bearer <access_token>` on subsequent RentCheck API calls.'
        refresh_token:
          type: string
          description: Long-lived refresh token accepted by `POST /v1/oAuth2/refresh_token`.
        org_id:
          type: string
          description: Organization id the tokens are scoped to (the caller's Zapier-configured `org_id`).
    oauth2_refresh_token_request_model:
      type: object
      required:
      - refresh_token
      properties:
        refresh_token:
          type: string
          description: The refresh token is used to request a fresh access token.
    oauth2_email_password_auth_request_model:
      description: Credentials for `POST /v1/oAuth2/emailPasswordAuth`. Either the account password OR the integration password (never both) must accompany the email.
      oneOf:
      - type: object
        required:
        - email
        - password
        properties:
          email:
            type: string
            format: email
            description: The user's email.
            example: user@email.com
          password:
            type: string
            description: The account password used on login.
            example: password123
      - type: object
        required:
        - email
        - integration_password
        properties:
          email:
            type: string
            format: email
            description: The user's email.
            example: user@email.com
          integration_password:
            type: string
            description: The integration password issued to the user via the RentCheck API integrations page. Callers presenting this value are authenticated as the underlying RentCheck user with no additional login round-trip.
            example: integration-abcdef123456
    oauth2_token_request_model:
      x-internal: true
      type: object
      description: Body for `POST /v1/oAuth2/token`. Used to complete the RentCheck OAuth2 authorization-code exchange (primary consumer is the Zapier integration).
      required:
      - client_id
      - client_secret
      - code
      properties:
        client_id:
          type: string
          description: Integration application id issued by RentCheck (aka `x-app-id`).
        client_secret:
          type: string
          description: Integration application secret issued by RentCheck (aka `x-app-secret`).
        code:
          type: string
          description: One-time authorization code returned by the RentCheck OAuth2 login flow. Consumed on success (the same code cannot be exchanged twice).
    oauth2_me_response_model:
      x-internal: true
      type: object
      description: Response body for `POST /v1/oAuth2/me`. Returns a synthetic identity payload the OAuth2 client can display back to the user.
      required:
      - email
      - timestamp
      - userId
      - orgId
      - appId
      properties:
        email:
          type: string
          format: email
          description: The authenticated user's email.
        timestamp:
          type: string
          description: Server-side localised timestamp string captured at the time the endpoint served the request. Purely informational.
        userId:
          type: string
          description: The authenticated user's RentCheck id.
        orgId:
          type: string
          description: Organization id decoded from the caller's access token.
        appId:
          type: string
          description: Integration application id decoded from the caller's access token.
  securitySchemes:
    bearerAuth:
      description: Authorization key needed to use the API
      type: http
      scheme: bearer
      bearerFormat: JWT
    x-app-id:
      description: Represents the identification of you application
      type: apiKey
      name: x-app-id
      in: header
      required: true
    x-app-secret:
      description: Represents the secret for your application
      type: apiKey
      name: x-app-secret
      in: header
      required: true