Credential resolution, the per-run access-token cache, and the opt-in store-backed token keeper. Usually used indirectly through ::quickbooks::api.

Sources. Every request takes an opts Map; its credential keys override context for that call, which is how one run acts for many companies:

Credentialopts keysContext variables
Access tokenaccess-tokenquickbooks.access.token
Token keepertoken-store (+ token-store-key)quickbooks.token.store
Refresh tokenrefresh-tokenquickbooks.refresh.token
App (for refresh)client-id, client-secretquickbooks.client.id, quickbooks.client.secret

When opts carries a primary credential (access-token, token-store or refresh-token) context credentials are ignored for the call; the app's client id and secret still fall back to context. Within one source the order is access token, keeper, refresh token. A credential key in opts that is blank or null is an Err naming the key, never a fallback to context. Per-call credentials are marked, so they are masked in call records.

Run cache. A refreshed access token is cached in the run's context (as a secret) until a minute before it expires, together with the newest refresh token, so a run that makes 200 calls refreshes once and a rotated refresh token is used for any later refresh in the same run. current-refresh-token(opts) returns that newest value: persist it at the end of the run if you are not using the keeper.

Token keeper (opt-in). Set quickbooks.token.store (or opts.token-store) to the name of a ::hot::store Map. Entries are keyed by realm id (or opts.token-store-key) and hold the refresh token, the current access token and their expiries. A run reads the entry, reuses its access token while fresh, and otherwise refreshes and writes the result back with ::hot::store/put-if, so rotated refresh tokens are persisted for you. Seed an entry once with keeper-seed (or let the first refresh use quickbooks.refresh.token).

Race note. Two runs that find the same stale entry can both refresh with the same refresh token. put-if lets exactly one write win; the loser re-reads the entry and uses the winner's tokens when they are fresh. Intuit normally returns the same refresh token within a day, so both refreshes succeed, but if your workload refreshes the same company from many concurrent runs, route refreshes through one scheduled function instead. Store values are not encrypted beyond the platform's storage; restrict who can read the store.

Context Vars

Optional
  • quickbooks.access.token
  • quickbooks.refresh.token
  • quickbooks.client.id
  • quickbooks.client.secret
  • quickbooks.token.store

Values

CACHE_PREFIX

CACHE_PREFIX: Str "quickbooks.token-cache."

CREDENTIAL_KEYS

CREDENTIAL_KEYS: Vec [
  "access-token",
  "refresh-token",
  "client-id",
  "client-secret",
  "token-store",
  "token-store-key",
  "realm-id",
  "environment",
  "minorversion",
  "retry",
  "request-id",
  "idempotent"
]

EXPIRY_MARGIN_SECONDS

EXPIRY_MARGIN_SECONDS: Int 60

NO_FALLBACK_KEYS

NO_FALLBACK_KEYS: Vec [
  "access-token",
  "refresh-token",
  "token-store",
  "token-store-key",
  "client-id",
  "client-secret"
]

Functions

access-token

fn (): Str
fn (opts: Map): Str

An access token for a call from opts and context (refreshing and caching as needed), or a TokenError.

token ::quickbooks::auth/access-token({refresh-token: ::hot::ctx/get("quickbooks.refresh.token")})

bearer

fn (creds: Map): Map

Resolve a bearer token for resolved credentials, using the run cache. Returns {token, cache-key, cached} (cached is true when the token came from the cache, so a 401 should evict and retry), or a TokenError.

Example

creds ::quickbooks::auth/resolve-credentials({}, "9341453")
auth ::quickbooks::auth/bearer(creds)
{Authorization: `Bearer ${auth.token}`}

cache-key

fn (creds: Map): Str?

The run-context key a token is cached under, or null for explicit access tokens. Derived from the app and the refresh token (or the keeper store and key), hashed.

Example

::quickbooks::auth/cache-key({kind: "token"})  // null
starts-with(::quickbooks::auth/cache-key({kind: "keeper", store: "quickbooks-tokens", key: "9341453"}), "quickbooks.token-cache.")  // true

credentials-from

fn (source: Map, realm-id: Str?): Map

Turn a source Map into resolved credentials: {kind: "token", token}, {kind: "keeper", store, key, seed-refresh-token, client-id, client-secret} or {kind: "refresh", refresh-token, client-id, client-secret}. realm-id keys keeper entries when no token-store-key is given. Returns a TokenError when nothing usable is set. Pure.

Example

creds ::quickbooks::auth/credentials-from({
  refresh-token: ::hot::ctx/get("quickbooks.refresh.token"),
  client-id: "ABcd123",
  client-secret: ::hot::ctx/get("quickbooks.client.secret")
}, "9341453")
creds.kind

ctx-source

fn (): Map

The credential source read from context, in the opts shape.

Example

source ::quickbooks::auth/ctx-source()
::quickbooks::auth/has-primary-credential(source)

current-refresh-token

fn (): Str?
fn (opts: Map): Str?

The newest refresh token known to this run for the credentials in opts / context: the rotated value when a refresh in this run returned one, else the configured one (null for access-token credentials). Persist it when you are not using the token keeper.

stored ::hot::ctx/get("quickbooks.refresh.token")
latest ::quickbooks::auth/current-refresh-token({refresh-token: stored})
if(ne(latest, stored), ::hot::store/put(::hot::store/Map({name: "quickbooks-tokens"}), "9341453", latest), null)

evict

fn (creds: Map, cache-key: Str?): Bool

Expire a cached access token (after a 401) while keeping the newest refresh token, and expire a keeper entry's access token. No-op for null.

Example

creds ::quickbooks::auth/resolve-credentials({}, "9341453")
auth ::quickbooks::auth/bearer(creds)

// After a 401, the next bearer call refreshes
::quickbooks::auth/evict(creds, auth.cache-key)

has-primary-credential

fn (source: Map): Bool

True when source carries access-token, token-store or refresh-token.

Example

::quickbooks::auth/has-primary-credential({token-store: "quickbooks-tokens"})  // true
::quickbooks::auth/has-primary-credential({realm-id: "9341453"})  // false

is-fresh

fn (entry: Any, now: Int): Bool

True when an entry has an access token that has not reached its margin-adjusted expiry.

Example

entry {access-token: "access", expires-at: 2000}
::quickbooks::auth/is-fresh(entry, 1000)  // true
::quickbooks::auth/is-fresh(entry, 3000)  // false

keeper-entry

fn (store-name: Str, key: Str): Map?

Read a keeper entry (null when absent). The entry holds tokens: never log it.

Example

entry ::quickbooks::auth/keeper-entry("quickbooks-tokens", "9341453")
if(is-some(entry), entry.updated-at, "not connected")

keeper-mint

fn (creds: Map, now: Int): Map

Return a fresh entry for keeper credentials: the stored one when fresh, else refresh and write back with put-if (re-reading on a lost race).

Example

creds ::quickbooks::auth/credentials-from({
  token-store: "quickbooks-tokens",
  client-id: "ABcd123",
  client-secret: ::hot::ctx/get("quickbooks.client.secret")
}, "9341453")
entry ::quickbooks::auth/keeper-mint(creds, ::hot::time/epoch-millis(::hot::time/now()))
entry.expires-at

keeper-refresh-token

fn (entry: Any, seed: Str?): Str?

The refresh token to use for a keeper entry: the stored one, else the seed. Null when neither exists.

Example

::quickbooks::auth/keeper-refresh-token({refresh-token: "stored"}, "seed")  // "stored"
::quickbooks::auth/keeper-refresh-token(null, "seed")  // "seed"

keeper-seed

fn (store-name: Str, key: Str, tokens: Str | Map): Map

Seed (or replace) a keeper entry with a refresh token, for example right after ::quickbooks::oauth/exchange-code. Pass the whole TokenSet to store its access token too. Returns the entry written.

redirect-uri "https://app.example.com/oauth/quickbooks"
cb ::quickbooks::oauth/callback-params({query: {code: "Q011abc", realmId: "9341453"}})
tokens ::quickbooks::oauth/exchange-code(cb.code, redirect-uri)
::quickbooks::auth/keeper-seed("quickbooks-tokens", cb.realm-id, tokens)

mark-entry

fn (entry: Any): Any

Mask the tokens in a keeper entry and return it unchanged. Null passes through. Exposed for testing.

Example

entry ::quickbooks::auth/mark-entry(::quickbooks::auth/keeper-entry("quickbooks-tokens", "9341453"))
is-some(entry)

merge-sources

fn (opts: Map, ctx: Map): Map

Pick the source for a call: opts when it has a primary credential (client id and secret still fall back to ctx), else ctx. Pure.

Example

merged ::quickbooks::auth/merge-sources({token-store: "quickbooks-tokens"}, {client-id: "ABcd123"})
merged.token-store  // "quickbooks-tokens"
merged.client-id  // "ABcd123"

resolve-credentials

fn (opts: Map, realm-id: Str?): Map

Resolve the credentials for a call from opts and context, marking per-call credentials so they are masked in call records. A credential key in opts that is blank or null is a TokenError naming the key.

Example

creds ::quickbooks::auth/resolve-credentials({access-token: ::hot::ctx/get("quickbooks.access.token")}, "9341453")
creds.kind

token-entry

fn (tokens: Map, now: Int): Map

The cached or stored form of a TokenSet: {access-token, expires-at, refresh-token, refresh-token-expires-at, updated-at}; expires-at is pulled in by EXPIRY_MARGIN_SECONDS.

Example

// 3600 seconds, less the 60 second margin, after now
::quickbooks::auth/token-entry({expires-in: 3600}, 1000)  // {expires-at: 3541000, updated-at: 1000}