OAuth — Shopify, Airtable, Google Sheets, WooCommerce

For four providers, you can skip the credential wrangling. Just click Connect, approve on their side, and Spelo handles everything else.

Provider	What you get
Shopify	Read-only access to products, collections, articles, pages
Airtable	Read-only access to the bases you select
Google Sheets	Read-only access to specific spreadsheets
WooCommerce	Read-only access to products, categories, tags

Under the hood Spelo stores encrypted OAuth tokens (AES-256-GCM) and refreshes them automatically. See Security → OAuth token handling.

Shopify

1. Dashboard → Data → Shopify → Connect with Shopify
2. Enter your *.myshopify.com domain
3. Approve the permissions on the Shopify auth screen:
   • read_products
   • read_collections
   • read_content
4. You’re redirected back. Spelo shows the product count. Done.

Spelo requests only read scopes. We cannot create orders, edit products, or access customer PII.

For Shopify Plus stores with restricted admin apps, you can alternatively configure manually with a Storefront Access Token — see Shopify adapter.

Airtable

1. Dashboard → Data → Airtable → Connect with Airtable
2. Approve on Airtable’s OAuth screen
3. Select the bases you want Spelo to have read access to. Scope is per-base.
4. Map Airtable tables to Spelo collections.

Tip

Airtable’s OAuth tokens expire every 60 minutes. Spelo refreshes them in the background — you don’t need to do anything. If a refresh fails (e.g. you revoked access), the dashboard shows a red “Reauthorize” button.

Alternative: Personal Access Token setup.

Google Sheets

1. Dashboard → Data → Google Sheets → Connect with Google
2. Approve the Google consent screen. Spelo requests https://www.googleapis.com/auth/spreadsheets.readonly.
3. Paste the spreadsheet ID (from the URL: https://docs.google.com/spreadsheets/d/{ID}/edit).
4. For each tab (sheet), define a collection — e.g. map tab Menu Items to collection menu_items.

Header row required. The first row of each tab must contain column names. The adapter uses those as field names.

Alternative: API key + public sheet.

WooCommerce

1. Dashboard → Data → WooCommerce → Connect with WooCommerce
2. Enter your store URL (e.g. https://example.com)
3. You’re redirected to the WooCommerce admin. Click Approve — Spelo receives a read-only consumer key/secret pair.
4. Spelo tests the connection and you’re done.

Revoking access

Each OAuth connection has Revoke in the dashboard. Revoking:

1. Calls the provider’s token revocation endpoint (so the token is dead even if we still had it).
2. Deletes the encrypted token from our DB.
3. Removes the adapter from your site; the AI will fall back to DOM-only mode.

If you delete your Spelo account, all OAuth tokens are revoked automatically (not just deleted).

Token refresh and reauthorization

OAuth providers issue short-lived access tokens (5-60 minutes) paired with long-lived refresh tokens. Spelo auto-refreshes access tokens before they expire — you don’t have to think about it.

What happens automatically

T-300s before expiry  →  Spelo exchanges refresh_token for new access_token
                         Stores new tokens in encrypted DB
                         AI keeps working with no interruption

The refresh job runs server-side on a 5-minute cron. Even if there’s no voice traffic for hours, your tokens stay fresh.

What can fail (and how Spelo recovers)

Failure	Detection	Recovery
Refresh token revoked by you (you logged out of the provider)	First refresh attempt returns invalid_grant	Dashboard shows banner: “Reauthorize Airtable”. Click → re-do OAuth flow.
Provider rotated the refresh token (Google/Airtable do this)	Refresh succeeds but returns a new refresh_token	Stored automatically. No user action needed.
Refresh token expired (Google: never; Airtable: 60 days inactivity)	Refresh returns invalid_grant after the inactive window	Banner + Reauthorize, same as revocation
Provider OAuth app removed by your org admin	First refresh returns invalid_client	Banner: “Connected app removed — reauthorize”
Spelo refresh job temporarily can’t reach the provider	Retries every 5 min for up to 1 hour	Auto-recovers. If still failing at +1h, you get an oauth.refresh_failed webhook event.

Reauthorization flow — what your visitors see during it

Nothing. Reauthorization happens in your dashboard, not on your live site. While the provider grant is broken:

1. The AI’s search_database calls return success: false with error oauth_expired
2. The agent gracefully falls back to DOM + knowledge-base mode (per adapter failures)
3. Visitors hear “I’m having trouble pulling live inventory right now, but here’s what I can tell you…”
4. No call drop, no error message to the visitor

You re-auth at your leisure. Most teams set up an alert on oauth.refresh_failed (webhook) and reauthorize within an hour, before significant traffic builds up.

Subscribing to refresh events

curl -X POST https://api.spelo.ai/v1/webhooks \
  -H "Authorization: Bearer vk_live_..." \
  -d '{
    "url": "https://yourapp.com/spelo-oauth-alert",
    "events": ["oauth.refresh_failed", "oauth.reauthorized"]
  }'

oauth.refresh_failed fires after 1 hour of retry failures (so you don’t get paged for transient blips). oauth.reauthorized fires when a user completes the Reauthorize flow.

Manual force-refresh

If you suspect a stale token (e.g. you just rotated your Shopify admin password), force a refresh:

curl -X POST https://api.spelo.ai/v1/sites/:id/adapter/refresh-token \
  -H "Authorization: Bearer vk_live_..."

Returns the new expiry timestamp. Use sparingly — automatic refresh handles 99% of cases.

Scopes reference

Provider	Requested scopes	Access token TTL	Refresh?
Shopify	read_products, read_collections, read_content	Long-lived (per session token)	No (token only invalidates when admin revokes)
Airtable	data.records:read, schema.bases:read	60 min	Yes — auto-refresh every 55 min
Google Sheets	spreadsheets.readonly	60 min	Yes — auto-refresh every 55 min
WooCommerce	read	Long-lived (key/secret pair)	No

Troubleshooting

• “Unable to connect” after approval — the redirect URL must match. If you host the dashboard on a custom domain, make sure it’s in Spelo’s configured OAuth redirects (email support@spelo.ai).
• “Invalid client” on callback — you’ve hit the provider’s OAuth rate limit. Wait 60s.
• Airtable shows empty base list — your user must have at least one base with “Creator” access. Collaborators can’t grant OAuth scopes on Airtable.

Connect a different data source

Overview Postgres MySQL MS SQL MongoDB Supabase Firebase Airtable Google Sheets Shopify WooCommerce REST API Webhook TS adapter Schema introspection