Pricefinder Oauth2 API

openapi: 3.2.0
info:
  description: Pricefinder API provides access to property, sale and listing searches as well as suburb statistics and SSO to the Pricefinder website capabilities.
  version: 1.13.1
  title: PriceFinder API v1.13.1 Oauth2 API
  contact:
    name: Pricefinder
  license:
    name: Terms and Conditions
    url: https://www.domain.com.au/group/api-terms-and-conditions/
servers:
- url: /v1
tags:
- name: OAuth2
paths:
  /oauth2/token:
    post:
      tags:
      - OAuth2
      description: 'Retrieve an oauth2 acces_token for use with Pricefinder API. A basic auth header is supported as an alternative to the form parameters for username and password.


        After retrieving the token, it must be either added as an authorization header(eg Authorization: Bearer <token>) or appended to the query (eg ?access_token=<token>).


        The api supports three ''flows'' for retrieving a token; client_credentials, refresh_token and authorization_code


        client_credentials


        The client credentials flow requires the api user to pass their user name and password to retrieve the token.


        code_authorization


        The code authorization flow is used to authenticate on behalf of a another user.

        To acquire authorization from a third party, direct that user to /v1/auth/authorize.html?client_id=<username>&state=<random_number>&redirect_uri=<callback_in_your_app>. Https is required.

        The client_id is your username.

        The state is a random string used to verify that the authorization request was generated by your webapp.

        The redirect_uri is the callback uri after the third party has accepted or declined the authorization request.


        eg https://api.pricefinder.com.au/v1/auth/authorize.html?client_id=username&state=123&redirect_uri=https%3A%2F%2Fyour.web.app%2Fsomepage


        The third party will authenticate and authorize access to the api on their behalf. If the user allows access, the third party is redirected to your.web.app/somepage?state=<state>&code=<authorization_code>


        eg https://your.web.app/somepage?state=123&code=9efc4ad1cca0bae6255ffd6db6cc85


        (If the user declines, a callback is made with query parameter error=access_denied)


        The api user can then retrieve an access token using this code from /v1/oauth2/token, using the ''authorization_code'' grant type.


        eg


        curl -X POST --header "Content-Type: application/x-www-form-urlencoded" --header "Accept: application/json" -d "grant_type=authorization_code&client_id=username&client_secret=password&code=9efc4ad1cca0bae6255ffd6db6cc85&redirect_uri=https%3A%2F%2Fyour.web.app%2Fsomepage" "https://api.pricefinder.com.au/v1/oauth2/token"


        This will return an access token, as well as a refresh token, which can be used to acquire access tokens in the future without requiring the third party to reauthorize.


        refresh_token


        A refresh token can be used to acquire a new access token without requiring the third party to re authorize the user. This method consumes the refesh token and returns a new access token and a new refresh token.


        Required Parameters:


        client_credentials => client_id, client_secret


        refresh_token => client_id, client_secret, refresh_token


        authorization_code => client_id, client_secret, redirect_uri, code


        Simple OAuth2 Demonstration / test


        Callback Example'
      operationId: getToken
      responses:
        '200':
          description: Token created
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientAccessToken'
        '401':
          description: Invalid username/password
          headers: {}
        '400':
          description: Bad Request
          headers: {}
      security: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  format: string
                  enum:
                  - client_credentials
                  - refresh_token
                  - authorization_code
                  default: client_credentials
                  description: OAuth 2 token grant flow type
                client_id:
                  type: string
                  format: string
                  description: username
                client_secret:
                  type: string
                  format: password
                  description: password
                refresh_token:
                  type: string
                  format: string
                  description: Refresh token
                code:
                  type: string
                  format: string
                  description: code provided through callback
                redirect_uri:
                  type: string
                  format: string
                  description: URI that was used to generate code
              required:
              - grant_type
              - client_id
              - client_secret
      summary: Get token
      x-summary-source: derived
components:
  schemas:
    ClientAccessToken:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: string
        refresh_token:
          type: string