Skip to content
Local environment Preproduction — not production data

Connecting a third-party provider (OAuth)

An App that connects an external system — a payroll vendor, a SaaS tool, DATEV — runs an OAuth authorization code flow against that provider. Factorial Code runs both redirect legs for you.

For the form side of it — the Connect button and how the result reaches the form — see Connecting an external account. This page is about the authorization itself.

Almost every provider requires redirect URIs to be registered in advance and then matches them exactly. But a webhook URL carries the workspace slug, and each customer’s installation of your App is its own deploy-{deployId} workspace:

https://code.factorialhr.com/platform/api/deploy-9f3c1ab8d2e4/webhooks/my-callback

That URL is different for every customer, so it can never be the registered one. Registering one customer’s URL and routing everybody through it is not a workaround — it makes one installation a dependency of all the others.

So the platform owns a single fixed redirect URI, and dispatches each callback to the installation it belongs to.

https://code.factorialhr.com/platform/api/oauth/callback

One string, for every App and every customer. Nothing per-workspace to keep in step, and no query parameters — providers compare the registered URI exactly.

Call fcode.oauth.start() from the process that renders your Connect button — typically a pre-render process — and give the form’s OAuth widget the authorizationUrl it returns.

const flow = await fcode.oauth.start({
authorizeUrl: "https://login.example.com/authorize",
clientId: fcode.env.PROVIDER_CLIENT_ID,
scope: ["openid", "offline_access", "payroll:read"],
onComplete: "oauth-callback",
data: { companyId, legalEntityId },
});
return { variables: { authorizeUrl: flow.authorizationUrl } };
Option
authorizeUrlThe provider’s authorization endpoint. Required.
clientIdThe client id registered with the provider. Required.
onCompleteThe process to run when the provider redirects back. Required, and it must already exist — starting a flow that names a missing process fails here, at render time, rather than after a customer has signed in.
scopeA list of scopes, or one already-joined string.
dataAnything this flow should carry to onComplete. Opaque to the platform and handed back untouched.
extraParamsProvider-specific authorization parameters (a nonce, an audience). They cannot override the ones the protocol depends on.
responseType"code" (the default) or "omit". Use "omit" for a redirect ceremony that is not a grant and issues no code — see Ceremonies that are not a grant.
versionTagPins onComplete to a version, so a flow started before a release still lands on the code it was started with.
pkceOn by default. Turn it off only for a provider that cannot cope with it.

A flow is valid for 15 minutes, which is enough to survive a provider sign-in with 2FA. The authorization URL can be opened more than once — a form re-render or a double click reaches the provider again with the same challenge — but it completes only once.

The platform runs your onComplete process itself. It does not need a webhook, public or otherwise: nobody is calling it over HTTP, so there is nothing to expose and nothing to authenticate.

Everything the token exchange needs is already in the parameters:

const { code, codeVerifier, redirectUri, data, state, error } = fcode.context.parameters;
if (error) {
return redirectToForm({ status: "error", message: "Authorization was refused." });
}
const tokens = await exchange({
code,
code_verifier: codeVerifier,
redirect_uri: redirectUri, // the provider compares this byte for byte
client_id: fcode.env.PROVIDER_CLIENT_ID,
client_secret: fcode.env.PROVIDER_CLIENT_SECRET,
});
await fcode.datastore.set(`tokens.${data.companyId}`, JSON.stringify(tokens));
return {
status: 302,
headers: {
Location:
"https://code.factorialhr.com/sdk/oauth-callback.html" +
"?status=success&value=" + encodeURIComponent(data.companyId) +
"&state=" + encodeURIComponent(state), // the form only accepts a completion that echoes it
},
};
Parameter
codeThe authorization code. Absent when the provider refused.
codeVerifierThe PKCE verifier for this flow. Absent when pkce was off.
redirectUriWhat the platform sent as the redirect URI. Replay it in the token exchange — providers compare the two exactly.
dataWhatever you passed to start().
stateThe flow’s state. Echo it in your redirect to the forms SDK page: the authorization URL always carries one, so the form rejects a completion that does not echo it.
error, errorDescription, errorUriPresent when the provider refused. All three are RFC 6749’s own, so they arrive by name rather than in providerParams.
providerParamsEverything else the provider put on its redirect. Untrusted provider input — validate it. Absent when it sent nothing else. See below.
providerParamsDroppedNames of any parameters the platform could not forward, so you can tell “the provider never sent it” from “the platform dropped it”. Absent when nothing was dropped.

Whatever the process returns becomes the HTTP response the browser follows, so ending with a 302 to the forms SDK callback page is what closes the popup and tells the form how it went.

Providers routinely answer with more than the protocol asks for, and some of it is not derivable from the code — Microsoft’s admin consent endpoint returns a tenant (and no code at all), QuickBooks a realmId, Shopify a shop and an hmac. Those arrive in providerParams:

const { providerParams = {}, data } = fcode.context.parameters;
// Shape-check before it is used for anything. A tenant id is a GUID; anything else
// did not come from the provider, whatever the redirect claimed.
const tenant = providerParams.tenant ?? "";
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tenant)) {
return redirectToForm({ status: "error", message: "Consent could not be verified." });
}
// What actually proves the consent: a token for that tenant. If this fails, the
// redirect told you nothing.
const tokens = await clientCredentialsFor(tenant);
await fcode.datastore.set(`tenant.${data.companyId}`, tenant);

A shape check is a filter, not proof. What proves a Microsoft admin consent is successfully acquiring a token for that tenant — the redirect only tells you where to try.

They are kept under their own key, never merged into the parameters above. The callback URL is public, so anything on it is attacker-controllable: a merge would let whoever holds an unspent state redraw data — and with it the tenant your process believes it is acting for — by appending a query parameter.

What does not reach it:

  • state, code, error, error_description and error_uri, which the platform already hands you by name.
  • Anything past 16 parameters, a 64-character name or a 1024-character value. Over-long values are dropped whole rather than truncated, so you never act on half an identifier. Whatever was dropped is named in providerParamsDropped, so a missing value is never silent.

A repeated query key keeps its first value: ?shop=a&shop=b arrives as shop: "a".

Some redirects are not an authorization code grant at all. Microsoft’s /common/adminconsent grants an application admin consent across a tenant; a GitHub App installation attaches an App to an account. Both take no response_type, and both come back with parameters of their own and no code. Ask for those with responseType: "omit":

const flow = await fcode.oauth.start({
authorizeUrl: "https://login.microsoftonline.com/common/adminconsent",
clientId: fcode.env.MS_CLIENT_ID,
responseType: "omit",
onComplete: "consent-granted",
data: { companyId },
});

The rest of the round trip is unchanged — same state, same single-use completion, same onComplete. Only the authorization URL differs, and code simply never arrives:

const { providerParams = {}, data } = fcode.context.parameters;
// { tenant: "9f3c1ab8-…", admin_consent: "True" }

PKCE is turned off for these automatically, whatever you pass: there is no code to exchange, so a challenge would be noise on the authorization URL and the verifier would reach your process for nothing.

"code" and "omit" are the only accepted values. "omit" is named for what the platform does rather than "none", which OAuth already registers for something else: a response type that is sent, asking the server to return nothing. There is no "token" either — an implicit response arrives in a URL fragment, and a fragment never reaches a server, so nothing would ever get back to the platform — see Limits.

  • fcode.oauth needs the platform. Like fcode.schedule and fcode.storage, it is backed by the workspace’s meta token, so it is unavailable under a local fcode run. Exercise an OAuth flow on the platform, from an installed App.
  • response_mode=fragment and the implicit flow cannot work: a URL fragment never reaches a server, so there is nothing to dispatch on. Use the authorization code flow.
  • A provider that omits state when refusing cannot be routed either; the platform sends the popup to the forms SDK page with an error instead.
  • A callback with no code still runs your process. Some endpoints — Microsoft’s admin consent among them — never issue one, and what they do return arrives in providerParams.
  • response_mode=form_post is unsupported: the callback is a GET, so a provider that POSTs its response back — Apple’s Sign in with Apple, for one — cannot be received.