ExQuickBooks v0.6.0 ExQuickBooks.OAuth

Functions for interacting with the OAuth API.

QuickBooks uses the three-legged OAuth 1.0a flow. For a human-readable overview of the whole flow and how to implement it, see e.g. oauthbible.com.

Request token

To start the authentication flow, your application needs to get a request token using get_request_token/1:

{:ok, request_token} = ExQuickBooks.get_request_token(callback_url)

The token is an ExQuickBooks.OAuth.RequestToken, see its documentation for more details.

You should redirect the user to request_token.redirect_url to authorise your application to access their QuickBooks data. After that step they are redirected to the given callback URL.

If you need to persist data (such as the request token) between this request and the callback, you could store that data e.g. in the current user’s (encrypted) session.

Callback

After authorisation, the user is redirected to your callback URL with these request parameters:

  • "realmId" - ID of the user’s QuickBooks realm. Note the camel-cased name.
  • "oauth_verifier" - Token verifier string you can use to retrieve an access token.

There are more parameters as well, but these are most relevant.

Access token

You can now exchange the request token, realm ID, and the verifier from the callback request parameters for an access token using get_access_token/3:

{:ok, access_token} = ExQuickBooks.get_access_token(request_token, realm_id, verifier)

Now you can store the access token and use it in API calls to authenticate on behalf of the user. The token is an ExQuickBooks.OAuth.AccessToken, see its documentation for more details.

Summary

Functions

Exchanges a request token, realm ID, and token verifier for an access token

Retrieves a new request token

Functions

get_access_token(request_token, realm_id, verifier)

Exchanges a request token, realm ID, and token verifier for an access token.

You should have previously received the realm ID and token verifier in the callback URL params as "realmId" and "oauth_verifier".

get_request_token(callback_url)
get_request_token(String.t) ::
  {:ok, ExQuickBooks.OAuth.RequestToken.t} |
  {:error, any}

Retrieves a new request token.

The callback URL must be an absolute URL where the user is redirected after authorising your application.

Returns the request token with a URL where your application should redirect the user as request_token.redirect_url.