Intuit OAuth 2.0 for QuickBooks Online, built on hot.dev/oauth2.

Flow

  1. Redirect the user to authorize-url(...). Intuit asks them to pick a company and approve your app.
  2. Intuit calls your redirect URI with ?code=...&state=...&realmId=.... callback-params(request) reads them; check state against the value you issued.
  3. exchange-code(code, redirect-uri) returns a TokenSet.
  4. Persist refresh-token and realm-id per company. Access tokens last an hour; refresh tokens last 100 days from their last use and at most five years in all.

Rotation. Refresh tokens rotate: refresh can return a different refresh token than the one you sent, and once it does the old value stops working. Every TokenSet carries the refresh token to keep (refresh-token) and rotated: true when it changed. Always persist it, or let the ::quickbooks::auth token keeper do that in a ::hot::store.

Token calls authenticate the app with HTTP Basic (client_secret_basic), as Intuit's SDKs do. The client id and secret come from opts (client-id, client-secret) or the quickbooks.client.id / quickbooks.client.secret context variables.

::oauth ::quickbooks::oauth

url ::oauth/authorize-url("ABcd123", "https://app.example.com/oauth/quickbooks", "csrf-123")

// In the callback handler, `request` is the inbound request:
request {query: {code: "Q011abc", state: "csrf-123", realmId: "9341453"}}
cb ::oauth/callback-params(request)
tokens ::oauth/exchange-code(cb.code, "https://app.example.com/oauth/quickbooks")
// persist tokens.refresh-token and cb.realm-id for this company

Context Vars

Optional
  • quickbooks.client.id
  • quickbooks.client.secret

Functions

app-credentials

fn (opts: Map): Map

The app's {client-id, client-secret} from opts, else context, with a per-call secret marked so it is masked in call records. A TokenError names what is missing; a key in opts that is blank or null is one too, never a fallback to context.

Example

app ::quickbooks::oauth/app-credentials({})
app.client-id

::quickbooks::oauth/app-credentials({client-id: "ABcd123", client-secret: ::hot::ctx/get("quickbooks.client.secret")})
Context Vars: quickbooks.client.id, quickbooks.client.secret

authorize-url

fn (client-id: Str, redirect-uri: Str, state: Str): Str
fn (client-id: Str, redirect-uri: Str, state: Str, opts: Map): Str

Build Intuit's consent URL. state is your CSRF token (Intuit requires one). Options: scopes (Vec or Str; default com.intuit.quickbooks.accounting; add openid email for the user's identity), code-challenge (an S256 PKCE challenge), and extra (any other parameters).

url ::quickbooks::oauth/authorize-url("ABcd123", "https://app.example.com/oauth/quickbooks", "csrf-123",
  {scopes: ["com.intuit.quickbooks.accounting", "openid", "email"]})

basic-auth

fn (client-id: Str, client-secret: Str): Str

The Authorization header value for token calls: Basic base64(client-id:client-secret).

Example

header ::quickbooks::oauth/basic-auth("ABcd123", ::hot::ctx/get("quickbooks.client.secret"))
{Authorization: header}

blank-option

fn (opts: Map, names: Vec): Str?

The first of names that opts has but with a blank or null value, else null. Such a key is an Err, never a fallback to context: a tenant whose credential is missing must not run on the project's. Exposed for testing.

Example

::quickbooks::oauth/blank-option({realm-id: ""}, ["realm-id", "environment"])  // "realm-id"
::quickbooks::oauth/blank-option({realm-id: "9341453"}, ["realm-id"])  // null

build-exchange-body

fn (code: Str, redirect-uri: Str, code-verifier: Str?): Map

The authorization_code grant body (client credentials go in the Basic header). code-verifier completes a PKCE flow.

Example

body ::quickbooks::oauth/build-exchange-body("Q011abc", "https://app.example.com/oauth/quickbooks", null)
body.grant_type  // "authorization_code"
body.code  // "Q011abc"

build-refresh-body

fn (refresh-token: Str): Map

The refresh_token grant body (client credentials go in the Basic header).

Example

body ::quickbooks::oauth/build-refresh-body(::hot::ctx/get("quickbooks.refresh.token"))
body.grant_type

build-revoke-request

fn (token: Str, client-id: Str, client-secret: Str): ::hot::http/HttpRequest

Build the revoke HttpRequest (JSON {token}, Basic client auth). Pure; exposed for testing.

Example

req ::quickbooks::oauth/build-revoke-request(::hot::ctx/get("quickbooks.refresh.token"), "ABcd123", ::hot::ctx/get("quickbooks.client.secret"))
req.url

build-token-request

fn (body: Map, client-id: Str, client-secret: Str): ::hot::http/HttpRequest

Build (without sending) the token-endpoint HttpRequest: a form-encoded grant body, HTTP Basic client authentication, and the x-include-refresh-token-hard-expires-in header so Intuit reports the five-year refresh-token limit. Pure; exposed for testing.

Example

body ::quickbooks::oauth/build-refresh-body(::hot::ctx/get("quickbooks.refresh.token"))
req ::quickbooks::oauth/build-token-request(body, "ABcd123", ::hot::ctx/get("quickbooks.client.secret"))
req.url
req.headers.Content-Type

callback-params

fn (request: Map): Map

Read Intuit's redirect: {code, state, realm-id, error, error-description} from the request's query (fields are null when absent). realm-id is the company the user picked; store it next to the refresh token. Compare state with the value you issued before exchanging the code.

Example

cb ::quickbooks::oauth/callback-params({query: {code: "Q011abc", state: "csrf-123", realmId: "9341453"}})
cb.realm-id  // "9341453"
cb.state  // "csrf-123"
cb.error  // null

exchange-code

fn (code: Str, redirect-uri: Str): TokenSet
fn (code: Str, redirect-uri: Str, opts: Map): TokenSet

Exchange the authorization code for a TokenSet. redirect-uri must match the one used for authorize-url. Options: client-id, client-secret (else context), code-verifier (PKCE).

Example

tokens ::quickbooks::oauth/exchange-code("Q011abc", "https://app.example.com/oauth/quickbooks")
tokens.refresh-token

// PKCE, with the app passed per call
::quickbooks::oauth/exchange-code("Q011abc", "https://app.example.com/oauth/quickbooks", {
  client-id: "ABcd123",
  client-secret: ::hot::ctx/get("quickbooks.client.secret"),
  code-verifier: "dBjftJeZ4CVP"
})

int-or-null

fn (value: Any): Int?

An Int from an Int or digit-only Str; null otherwise. Guards Int() so bad input never halts a run.

Example

::quickbooks::oauth/int-or-null("42")  // 42
::quickbooks::oauth/int-or-null("4x")  // null

is-blank

fn (value: Any): Bool

True for null, "" and whitespace-only strings (unset env placeholders arrive as "").

Example

::quickbooks::oauth/is-blank("  ")  // true
::quickbooks::oauth/is-blank("9341453")  // false

mark-tokens

fn (body: Map): Map

Mask the tokens in a token-endpoint response and return it unchanged. Only the tokens: marking the whole body would also hide values like token_type and scope. Exposed for testing.

Example

body ::quickbooks::oauth/mark-tokens({access_token: ::hot::ctx/get("quickbooks.access.token"), token_type: "bearer"})
body.token_type

normalize-scopes

fn (scopes: Any): Str

Scopes as a space-separated Str from a Vec or a space/comma-separated Str; SCOPE_ACCOUNTING when null or empty.

Example

::quickbooks::oauth/normalize-scopes(null)  // "com.intuit.quickbooks.accounting"
::quickbooks::oauth/normalize-scopes("openid,email")  // "openid email"
::quickbooks::oauth/normalize-scopes(["openid", "openid"])  // "openid"

refresh

fn (refresh-token: Str): TokenSet
fn (refresh-token: Str, opts: Map): TokenSet

Exchange a refresh token for a new TokenSet (no cache). Persist the returned refresh-token: Intuit rotates it, and the old value stops working once a new one is issued. A revoked or expired refresh token gives error-code: "invalid_grant"; the company must connect again. Options: client-id, client-secret (else context).

tokens ::quickbooks::oauth/refresh(::hot::ctx/get("quickbooks.refresh.token"))
if(tokens.rotated, ::hot::store/put(::hot::store/Map({name: "quickbooks-tokens"}), "9341453", tokens.refresh-token), null)

revoke

fn (token: Str): Bool
fn (token: Str, opts: Map): Bool

Revoke a refresh or access token, disconnecting the app from the company (revoking the refresh token also ends its access tokens). Returns true, or a TokenError. Options: client-id, client-secret.

Example

result ::quickbooks::oauth/revoke(::hot::ctx/get("quickbooks.refresh.token"))
if(is-err(result), err-message(result), "disconnected")

send-token-request

fn (req: ::hot::http/HttpRequest, prefix: Str): Map

Send a token request; the decoded body on 2xx with its tokens marked so they are masked in call records, else a TokenError prefixed with prefix.

Example

body ::quickbooks::oauth/build-refresh-body(::hot::ctx/get("quickbooks.refresh.token"))
req ::quickbooks::oauth/build-token-request(body, "ABcd123", ::hot::ctx/get("quickbooks.client.secret"))
response ::quickbooks::oauth/send-token-request(req, "quickbooks: token refresh failed")
response.expires_in

token-error

fn (message: Str): TokenError
fn (prefix: Str, payload: Any): TokenError

Build a TokenError. The 1-arity form wraps a message; the 2-arity form describes a failed token response ({status, body, headers}) or transport error, prefixed with prefix.

Example

::quickbooks::oauth/token-error("quickbooks: no credentials").message  // "quickbooks: no credentials"

failed ::quickbooks::oauth/token-error("quickbooks: token refresh failed", {status: 400, body: {error: "invalid_grant"}})
failed.error-code  // "invalid_grant"
failed.message  // "quickbooks: token refresh failed: invalid_grant"

token-set

fn (body: Map, sent-refresh-token: Str?, now: Int): TokenSet

Turn Intuit's token response into a TokenSet (pure). sent-refresh-token is the refresh token the request used (null for a code exchange): when Intuit's response has no refresh_token the sent one is kept, and rotated says whether the value changed. now is epoch ms.

Example

body {access_token: "access", refresh_token: "new", expires_in: 3600}
tokens ::quickbooks::oauth/token-set(body, "old", 1000)
tokens.rotated  // true
tokens.refresh-token  // "new"
tokens.expires-at  // 3601000

Types

TokenError

TokenError type {
    message: Str,
    status: Int?,
    error-code: Str?,
    error-description: Str?,
    intuit-tid: Str?
}

A credential or token-endpoint failure. message is readable, e.g. "quickbooks: token refresh failed: invalid_grant (Token invalid)". error-code / error-description carry Intuit's OAuth error / error_description, and intuit-tid the response's intuit_tid header for support requests. Token values never appear in messages.

TokenSet

TokenSet type {
    access-token: Str,
    refresh-token: Str?,
    rotated: Bool,
    expires-in: Int?,
    expires-at: Int?,
    refresh-token-expires-in: Int?,
    refresh-token-expires-at: Int?,
    refresh-token-hard-expires-in: Int?,
    token-type: Str?,
    id-token: Str?,
    scope: Str?
}

The result of a code exchange or refresh.

  • access-token - the bearer token (about an hour)
  • refresh-token - the refresh token to persist; it may differ from the one you sent
  • rotated - true when refresh-token differs from the token sent
  • expires-in, expires-at - access-token lifetime (seconds) and expiry (epoch ms)
  • refresh-token-expires-in, refresh-token-expires-at - Intuit's x_refresh_token_expires_in (rolling, about 100 days)
  • refresh-token-hard-expires-in - the absolute five-year limit (x_refresh_token_hard_expires_in), when Intuit returns it
  • token-type, id-token (OpenID scopes only), scope