Skip to content

External APIs Overview

Workbench AI integrates with several third-party services. This page documents which APIs are used, what for, and where they are wired, without exposing any sensitive keys.

All secrets (API keys, webhook secrets, service role keys) are configured via environment variables and must never be committed to git. Use only placeholders like YOUR_STRIPE_SECRET_KEY in documentation.

Stripe

Stripe is used for subscription billing, customer billing portal, and historical invoice data. It is not used for per-invoice card processing inside Workbench itself (Greyhaven Payments is used there).

Usage areas

  • Subscriptions (SaaS billing)

    • Creating subscriptions via Checkout.
    • Managing subscriptions via Billing Portal.
    • Reactivating/correcting subscriptions.
    • Webhooks for subscription lifecycle events.

  • Invoices & payment history (SaaS side)

    • Fetching historical Stripe invoices.
    • Mirroring invoice/payment events into Supabase (payment_history).

API surfaces

Stripe Checkout

Used by:

  • create-checkout-session edge function
  • upgrade-checkout-session edge function (indirectly via subscription updates)
  • reactivate-subscription edge function

Key behavior:

  • stripe.checkout.sessions.create({ ... }) with:
    • mode: 'subscription'
    • customer: <stripe_customer_id>
    • line_items: [{ price: <PRICE_ID>, quantity: 1 }]
    • Metadata: company_id, plan_name, source, feature, user_id, referral.
    • Hosted URLs for success_url and cancel_url.

Config (env vars, placeholders only):

  • STRIPE_SECRET_KEY="YOUR_STRIPE_SECRET_KEY"
  • STRIPE_STARTER_PRICE_ID="price_XXX_STARTER"
  • STRIPE_PROFESSIONAL_PRICE_ID="price_XXX_PROFESSIONAL"

Billing Portal

Used by:

  • create-portal-session edge function

Key behavior:

  • stripe.billingPortal.sessions.create({ customer, return_url }).
  • Customer ID is resolved from subscriptions or fetched via Stripe.

Subscriptions

Used by:

  • get-stripe-subscription edge function
  • sync-stripe-subscriptions edge function
  • reactivate-subscription, upgrade-checkout-session

Key behavior:

  • stripe.subscriptions.retrieve(<subscription_id>) to get:
    • Status (trialing, active, past_due, etc.).
    • Items and recurring price (amount, interval).
    • Trial dates (trial_start, trial_end).
    • Current period start/end.

Invoices

Used by:

  • get-upcoming-invoice edge function
  • get-customer-invoices edge function
  • sync-payment-history edge function

Key behavior:

  • stripe.invoices.retrieveUpcoming({ customer, subscription }) for upcoming charges.
  • stripe.invoices.list({ customer, status }) for historical invoices.

Webhooks

Used by:

  • stripe-webhook edge function

Key behavior:

  • Receives events like:
    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.payment_succeeded
  • Verified via:
stripe.webhooks.constructEventAsync(rawBody, signature, STRIPE_WEBHOOK_SECRET)

Config (env vars):

  • STRIPE_WEBHOOK_SECRET="whsec_..." (per environment)

Stripe configuration

Actual product/price, webhook endpoint configuration, and Dashboard settings are maintained in Stripe itself. This doc only describes usage patterns; see internal ops docs for deployment-specific configuration.

AI providers

Workbench AI uses an external AI provider for image generation in the Nameplate Studio. The implementation is intentionally abstracted to avoid locking in a specific vendor in docs.

Nameplate generation

Used by:

  • generate-nameplate edge function
  • Library & design flows (to display generated assets)

Key behavior:

  • Edge function constructs a prompt for a jewelry nameplate design.
  • Calls an external image API (e.g. DALL·E / compatible service) with that prompt.
  • Receives image bytes/URL, stores the image in Supabase Storage (nameplates bucket).
  • Inserts a row into nameplates with metadata and usage tracking.
  • Tracks monthly usage per user via nameplate_usage.

Config (env vars, placeholders):

  • OPENAI_API_KEY="YOUR_IMAGE_API_KEY"

Abstraction

The implementation references a specific provider in code today, but you can swap it out for any compatible image API by:

  • Updating the HTTP call in generate-nameplate.
  • Keeping the nameplates schema and storage behavior compatible.

Email / notifications (future)

As of this documentation pass, outbound notifications (email/SMS) are not yet fully wired into an external transactional email API inside this repo snapshot. When that changes, document:

  • Which provider is used (e.g. SendGrid, Postmark, SES).
  • Which flows send emails (invoices, pay links, affiliate notifications).
  • How unsubscribe / compliance is handled.

Placeholder env vars for future email integration:

  • EMAIL_PROVIDER_API_KEY="YOUR_EMAIL_API_KEY"
  • EMAIL_FROM_ADDRESS="no-reply@your-domain.com"

Greyhaven Payments (conceptual)

The Payments section in the app refers merchant users to Greyhaven Payments for invoice and pay-link processing. The actual card processing gateway is external and not fully configured in this repo.

What’s modeled in this codebase:

  • invoices and invoice_line_items tables (internal representation of invoices).
  • pay_links and pay_link_line_items tables (internal representation of payment links).
  • Temporary link_url values for pay links are generated in PayLinkCreation (e.g. https://payments.greyhavengroup.com/pay/<code>).
  • gateway_payment_id and gateway_link_id fields are reserved for future integration.

What is not in this repo:

  • Actual Greyhaven Payments API client.
  • Webhooks from Greyhaven informing pay_links or orders of payment success.

Production integration

When integrating Greyhaven’s API, ensure:

  • All callbacks verify signatures or shared secrets.
  • Payment status updates (paid, failed, refunded) are mirrored into pay_links, orders, and any reporting tables.
  • No raw card data ever touches Workbench AI servers.

Other integrations

Supabase

While not an "external API" in the same sense, the SPA uses the Supabase JavaScript client to talk to Postgres, Auth, and Storage:

  • @supabase/supabase-js initialized with:
    • VITE_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_URL
    • VITE_SUPABASE_ANON_KEY / NEXT_PUBLIC_SUPABASE_ANON_KEY

Usage patterns:

  • supabase.from('table').select(/* ... */) for data.
  • supabase.auth.signInWithPassword(...), supabase.auth.getSession() for auth.
  • supabase.storage.from('bucket').upload(...), getPublicUrl(...) for files.

Config (placeholders):

  • VITE_SUPABASE_URL="https://YOUR_PROJECT.supabase.co"
  • VITE_SUPABASE_ANON_KEY="YOUR_SUPABASE_ANON_KEY"

See:

Security & configuration summary

  • All third-party API keys and secrets are supplied via env vars.
  • Never log full keys; log the presence/absence only, or masked prefixes when debugging.
  • For multi-environment setups:
    • Keep variable names consistent across dev/stage/prod.
    • Change only the values.

Quick checklist when adding a new external API:

  1. Define placeholder env vars (e.g. THIRD_PARTY_API_KEY).
  2. Store secrets in the appropriate configuration (Supabase project, hosting platform, or secret manager).
  3. Add a short entry to this page under a new section.
  4. Ensure edge functions or backend code handle:
    • Network timeouts and retries.
    • Rate limiting / backoff.
    • Clear error messages for the frontend.