ExQuickBooks v0.3.0 ExQuickBooks.OAuth

Authentication functions for OAuth 1.0a.

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 and secret using get_request_token/0:

{:ok,
 %{"oauth_token" => request_token,
   "oauth_token_secret" => request_token_secret},
 redirect_url} = ExQuickBooks.get_request_token

That function will also give you the URL where you should redirect the user to authorise your application to access their QuickBooks data. After that step they will be redirected to the :callback_url you’ve set in the configuration.

If you need to persist data (such as the request token and secret) 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" - Verification string you can use to retrieve access credentials.

Access token

You can pass the verifier with the previous request token to get_access_token/3 in order to retrieve an access token and secret:

{:ok,
 %{"oauth_token" => access_token,
   "oauth_token_secret" => access_token_secret}} =
 ExQuickBooks.get_access_token(request_token, request_token_secret, verifier)

Your application should now store the realm ID, access token, and secret. Use them in API calls to authenticate on behalf of the user.

Summary

Functions

Exchanges an authorised request token and a token verifier for an access token. The secret is used for signing the request

Retrieves a new OAuth request token

Types

response_body()
response_body() :: %{required(String.t) => String.t}

Functions

get_access_token(request_token, request_token_secret, verifier)
get_access_token(String.t, String.t, String.t) ::
  {:ok, response_body} |
  {:error, any}

Exchanges an authorised request token and a token verifier for an access token. The secret is used for signing the request.

The token verifier required with this call was returned previously with the callback URL params.

The response body contains the following keys:

  • "oauth_token" - The access token associated with the user.
  • "oauth_token_secret" - The access token secret associated with the user.
get_request_token()
get_request_token ::
  {:ok, response_body, String.t} |
  {:error, any}

Retrieves a new OAuth request token.

Returns the token response and a URL where your application should redirect the user.

The response body contains the following keys:

  • "oauth_token" - The request token associated with the user.
  • "oauth_token_secret" - The request token secret associated with the user.

Note that the redirect URL is prepopulated with the request token.