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:
| Credential | opts keys | Context variables |
|---|---|---|
| Access token | access-token | quickbooks.access.token |
| Token keeper | token-store (+ token-store-key) | quickbooks.token.store |
| Refresh token | refresh-token | quickbooks.refresh.token |
| App (for refresh) | client-id, client-secret | quickbooks.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
quickbooks.access.tokenquickbooks.refresh.tokenquickbooks.client.idquickbooks.client.secretquickbooks.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}