DEV Community: WeInc

Sending website form entries to Asana, Pipedrive and other tools: OAuth lessons

WeInc — Mon, 02 Nov 2026 11:17:23 +0000

Every website form eventually gets the same request: "Can the entries go straight into our CRM?" Then the next one asks for Asana. Then Linear. Then the email list.

Each vendor has an OAuth flow, and each one looks standard until you build it. These are the lessons from wiring form entries into Asana, Pipedrive, Linear and Kit (formerly ConvertKit). Most of them apply to any OAuth integration where your server acts on a user's behalf long after they clicked "Connect".

Start with one small spec per vendor

The temptation is a big if (vendor === "pipedrive") chain. It falls apart by the third vendor. What worked better was a single generic flow plus a small description of each vendor:

type VendorSpec = {
  id: string;
  authorizeUrl: string;
  tokenUrl: string;
  clientAuth: "basic" | "body";   // where client_id/secret go on token calls
  bodyFormat: "form" | "json";
  authorizeParams?: Record<string, string>; // scope and friends
  defaultExpiresIn?: number | null; // when the reply has no expires_in
  apiBase?(tokenReply: unknown): string | null; // per-account API host
  revoke?(tokens: Tokens): Promise<void>;
};

Every quirk below became one field in that spec. Adding a vendor became a short object, not a new code path.

The per-vendor quirks

Pipedrive: the API host comes from the token reply. Pipedrive returns an api_domain with the tokens, something like https://yourcompany.pipedrive.com. API calls go to that host, not a single global one. Store it next to the tokens and read it back on every call. It can also come back on refresh, so update it then too.

Pipedrive also expects client credentials as HTTP Basic auth on token calls, not in the body:

const basic = "Basic " + Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
await fetch("https://oauth.pipedrive.com/oauth/token", {
  method: "POST",
  headers: { authorization: basic, "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri }),
});

Send them in the body instead and you get a generic auth error that does not say why.

Asana: tokens last an hour, and ask for the narrow scope. Asana access tokens expire after about an hour, so refreshing is not an edge case, it is the normal path for any form that gets submitted more than an hour after someone connected. For creating tasks from form entries, tasks:write is enough. Ask for the smallest scope that does the job; it makes the consent screen less alarming and the app review shorter.

Linear: scopes are comma separated. Most vendors want scopes separated by spaces. Linear wants commas: read,issues:create. Space-separated scopes do not fail loudly, you just end up with less access than you expected. issues:create is the narrowest scope that can create issues, and actor=user makes issues appear as created by the person who connected.

Kit: refresh tokens are single use. Kit's v4 OAuth sends client credentials in a JSON body and rotates the refresh token every time you use it. If you refresh and fail to save the new refresh token (a crash, a timeout writing to the database), the connection is dead and the user has to reconnect. Two consequences:

Persist the new tokens before doing anything else with them.
Avoid two parallel refreshes for the same connection. The loser will present a refresh token that has already been consumed.

Missing expires_in. Not every reply includes it. Keep a per-vendor default (Kit's tokens last about two hours) and treat "null" as "does not expire" only when you know that is true for that vendor.

Refresh before expiry, and once more after a 401

Two rules cover nearly all token failures:

Refresh early. If the token expires within the next few minutes, refresh before the call. A five-minute margin handles clock skew and slow requests.
Retry once after a 401. Tokens get revoked or expire early for reasons you cannot see. On a 401, force a refresh and retry the request exactly once. If that fails too, stop.

async function callWithToken(userId: string, doCall: (token: string) => Promise<Response>) {
  let token = await getToken(userId);                 // refreshes if expiring soon
  if (!token) return { ok: false, reason: "not_connected" };

  let res = await doCall(token);
  if (res.status === 401) {
    token = await getToken(userId, { force: true });  // one forced refresh
    if (!token) return { ok: false, reason: "reconnect_needed" };
    res = await doCall(token);
  }
  return { ok: res.ok, status: res.status };
}

function needsRefresh(expiresAt: string | null, now = Date.now()) {
  return !!expiresAt && Date.parse(expiresAt) - 5 * 60_000 <= now;
}

When the vendor refuses the refresh itself (an invalid_grant, usually), mark the connection as revoked and tell the user to reconnect. Retrying in a loop only gets you rate limited.

One detail that bites: some vendors return a new refresh token on refresh and some do not. When the reply has no refresh token, keep the old one. Overwriting it with null quietly breaks the next refresh an hour later.

Seal tokens at rest

Access and refresh tokens are passwords to someone else's account. Encrypt them before they hit the database, with a key that lives outside the database (an environment secret or a key manager). Authenticated encryption such as AES-256-GCM is the usual choice, because tampering is detected on decrypt.

A few practical points:

Encrypt both tokens, not just the refresh token. A one-hour access token is still enough to read a CRM.
Never log them. Log the vendor, the user ID and the HTTP status.
Store non-secret metadata (account name, API host, expiry) in plain columns so you can debug without decrypting anything.

Disconnect means stop sending

When a user disconnects, three things should happen:

Revoke at the vendor if they offer an endpoint. Asana, Linear and Pipedrive all do. Revoking the refresh token usually kills the access token too. Treat a failed revoke as a warning, not a blocker; the user still wants to be disconnected.
Delete or mark the stored tokens as revoked.
Disable every form destination that used this connection. This is the one people forget. Otherwise the next form submission tries a dead token, fails, and the entry either vanishes or lands in an error log nobody reads.

Disabling with a clear status ("disabled: connection removed") also lets your UI tell the site owner exactly why entries stopped going to Pipedrive, instead of leaving them to guess.

The same applies when a refresh fails permanently. Mark the destination as needing reconnection, keep the form entries in your own storage so nothing is lost, and tell the owner.

Installs that start on the vendor's side

Marketplaces like Pipedrive's let users install your app from the vendor's own listing page. That means the OAuth flow can start without your app having created a state value first, and without the user being signed in to your product.

Plan for it:

Accept a callback that arrives without your usual state, but only for vendors you have marked as marketplace-installable. Everywhere else, a missing or mismatched state must still fail.
If the user is not signed in, park the authorization code briefly (it expires fast, so minutes, not hours), send them to sign in or sign up, then finish the exchange.
Expect reviewers to test this path. A marketplace review will click "Install" from the listing, not from your settings page.

Things I would do from day one

One generic flow, one spec per vendor.
Tests for each spec using a fake fetch: check the header shape, the body format, and the scope string.
A five-minute refresh margin and a single retry on 401.
Encrypted tokens, plain metadata.
Disconnect disables destinations, and failed refresh flags them.
Keep every form entry in your own database first, then forward it. If an integration breaks, nothing is lost and you can resend.

That last one matters more than any OAuth detail. The CRM is a destination, not the store of record.

These notes come from building form integrations for WeInc (we.inc), a website builder. The patterns are vendor-neutral, though, and the docs for each provider are worth reading in full before you start: they are short, and every quirk above is in there somewhere.

Turning a Shopify store into a full website with Buy Buttons

WeInc — Mon, 02 Nov 2026 11:17:23 +0000

A lot of small brands start on Shopify and stay there because it works. Checkout, payments, taxes, inventory and order emails are solved. The part that often feels cramped is everything around the products: the story, the long landing pages, the blog, the booking form, the campaign page that needs a layout no theme section offers.

You can keep Shopify for what it does well and build the rest of the site however you like, then drop products into it with Buy Buttons. This post walks through how that works under the hood, when it is worth doing, and the things that tend to go wrong.

What a Buy Button actually is

The Buy Button is a small JavaScript library that Shopify hosts on its CDN. It renders a product card (image, title, price, variant picker, add to cart) and a slide-out cart on any web page. When the shopper clicks checkout, they are sent to the normal Shopify checkout for that store.

Under the hood it talks to the Storefront API, Shopify's public, read-mostly GraphQL API meant for custom storefronts. That is the key idea: your separate site never touches the Admin API from the browser. It only uses a token that is designed to be public.

A minimal embed looks like this:

<div id="product-1"></div>
<script src="https://sdks.shopifycdn.com/buy-button/latest/buy-button-storefront.min.js"></script>
<script>
  const client = ShopifyBuy.buildClient({
    domain: "your-store.myshopify.com",
    storefrontAccessToken: "YOUR_STOREFRONT_TOKEN",
  });

  ShopifyBuy.UI.onReady(client).then((ui) => {
    ui.createComponent("product", {
      id: "1234567890", // numeric product ID
      node: document.getElementById("product-1"),
    });
  });
</script>

Two values matter: the store's myshopify.com domain and a Storefront access token. The product ID is the numeric ID you can see in the admin URL of the product.

Where the Storefront token comes from

If you are setting this up for one store by hand, the Buy Button sales channel in the Shopify admin will generate the embed code and token for you. That is the simplest route.

If you are building an app that does this for many stores, you create the token yourself through the Admin GraphQL API, using the store's admin access token on your server:

mutation CreateStorefrontToken($input: StorefrontAccessTokenInput!) {
  storefrontAccessTokenCreate(input: $input) {
    storefrontAccessToken { accessToken }
    userErrors { message }
  }
}

Your app needs the right scopes for this to work. The ones that matter for a Buy Button are the unauthenticated_* family, which describe what the Storefront token is allowed to do on behalf of anonymous shoppers:

unauthenticated_read_product_listings so the token can read products and prices.
unauthenticated_read_checkouts and unauthenticated_write_checkouts so it can create and read carts.

Plus something like read_products if your own app needs to list the catalog in an admin screen.

Notice what is absent: nothing about customers, orders or payments. That is deliberate. The Storefront token sits in page source where anyone can read it, so it should only be able to do what an anonymous shopper on the store could already do.

Two habits that save trouble later:

Reuse, don't multiply. A store can only hold a limited number of Storefront tokens. Before creating one, list the existing tokens (shop { storefrontAccessTokens(first: 50) { ... } }) and reuse yours if it is there. Give it a recognisable title so you can find it.
Validate what you got back. Check that the mutation returned a token and no userErrors before you write it into a page. A silent empty string produces a Buy Button that renders nothing, with no obvious error.

The flow from click to order

The order of events is worth spelling out, because it explains most of the edge cases:

Your page loads the Buy Button script and fetches product data through the Storefront API.
The shopper picks a variant and adds it to the cart. The cart lives on Shopify; the script keeps a reference in the browser.
On checkout, the shopper leaves your domain and lands on the store's Shopify checkout.
Payment, tax, shipping rates, discount codes and the order confirmation all happen on Shopify, exactly as they would from a theme.

Because checkout never runs on your site, you are not handling card data, and your site is not in PCI scope for it. Orders show up in the Shopify admin like any other order, attributed to the Buy Button channel.

When a separate site beats a theme

A theme is still the right answer for most stores. A separate site with Buy Buttons is worth it when:

Products are a small part of the site. A studio, a course creator, a restaurant selling a few jars of sauce, a band selling merch. The site is mostly content, and a full store theme is overkill.
You need layouts the theme fights. Long-form launch pages, interactive explainers, or a design system you already use elsewhere.
The site already exists. Adding commerce to a working marketing site is easier than migrating it into Liquid.
You sell in several places. The same product can appear on a blog post, a landing page and a partner microsite, all feeding one inventory.

It is the wrong choice when you rely heavily on theme apps (reviews widgets, bundles, upsell apps). Most of those inject into theme templates and will not appear on your separate site.

Pitfalls

Embedding the wrong token. The Admin API token must never reach the browser. If you see shpat_ style tokens in front-end code, stop. Only the Storefront token belongs in page source.

Hard-coding product IDs without a fallback. If a product is deleted or unpublished from the Buy Button channel, the component renders empty. Keep a plain "View on store" link next to each embed, pointing at https://your-store.myshopify.com/products/handle. If the script fails, people can still buy.

Forgetting the sales channel. Products must be available to the channel your token belongs to. A product that is active in the store but not published to that channel will not load through the Storefront API.

Prices that look stale. The Buy Button fetches live prices, but any price you also typed into your own copy will not update. Let the component show the price and keep it out of your headings.

Two domains, two analytics stories. The shopper browses on your domain and pays on Shopify's. Set up cross-domain tracking, or accept that your site analytics will see "clicked checkout" and Shopify will see "order placed", and join them by date rather than by session.

Expiring admin tokens in apps. If you are building an app, newer Shopify installs hand you expiring offline tokens (around an hour) plus a refresh token. That only matters for your server-side admin calls, like creating the Storefront token. The Storefront token itself does not expire this way, so pages you already published keep working.

Script loading order. If your site is a single-page app, the #product-1 node might not exist yet when the script runs. Create components after the element mounts, and clean them up when it unmounts, or you will get duplicate cards on route changes.

A practical setup

For a small brand, my default is:

Shopify stays the source of truth for products, stock and orders.
The website is whatever is fastest to edit for the people running it.
Each product section has a Buy Button plus a plain text link to the product on the Shopify store.
One Storefront token per store, created once, reused, and scoped to the unauthenticated_* permissions only.

We built this flow into the Shopify app for WeInc (we.inc), where a merchant installs it, the app creates the Storefront token, and the generated site gets Buy Buttons for the store's products. The same pattern works fine by hand with the Buy Button channel and a static site, which is a good way to test it before committing to any tooling.

The main thing to remember: Shopify keeps the money part, your site keeps the story. As long as the token you embed can only do what an anonymous shopper can do, the split is safe and simple.