classroomio/prd/zapier

Zapier Integration PRD

Status

• Draft

Purpose

Ship a Zapier integration that lets non-engineering teams connect ClassroomIO to the tools they already use (CRMs, HRIS, Slack, spreadsheets, email platforms, ticketing) without writing code. The integration must work today against the existing public API and silently upgrade to real-time delivery as the webhooks platform lands.

Problem Statement

ClassroomIO already exposes a versioned public REST API at /public-api/v1/* and ships an MCP server, but those surfaces only serve engineering teams. The customers who run training programs (HR, customer success, sales enablement) cannot:

• Enroll learners automatically when a contact reaches a CRM stage.
• Sync course completions and certificates to HRIS, Drive, or BI warehouses.
• Trigger Slack/email workflows on learner activity.
• Connect ClassroomIO into the no-code stacks (Zapier, Make, n8n, Pipedream) that those teams already operate.

The dashboard already advertises Zapier as an Automation tab (/org/[slug]/automation/zapier) and the automation-key system supports type: 'zapier', but the page is a coming-soon callout and no Zapier app exists. We have customers who need this integration shipped now.

Confirmed Decisions

These are locked before implementation begins:

1. Distribution: ship as a private Zapier app via a single shared invite URL first; promote to the public Zapier directory after ~5 paying orgs are using it and v1 is stable.
2. Plan gating: Early Adopter+ only. Access is binary — either your plan includes Zapier or it doesn't. No monthly task credits. Per-minute rate limits still apply as abuse protection.
3. Plan downgrade behavior: hard cutoff. When an org drops below Early Adopter, all existing OAuth grants are revoked immediately. No grace period.
4. Authentication: OAuth 2.0 authorization code flow with refresh tokens, shipping in v1. No API-key-paste fallback for Zapier. Direct API consumers (Make, n8n, Pipedream, raw curl) keep using existing type: 'api' automation keys; Zapier exclusively uses OAuth.
5. Scopes: zapier:read and zapier:write exist as OAuth scopes. Zapier requests both at connection time; the consent screen lets admins downgrade to read-only.
6. Triggers in v1: polling only. No webhook dependency. Real-time REST Hooks ship in v1.1 once the webhooks PRD lands.
7. Trigger scope: org-wide by default, with optional Course and Tag dropdown filters per trigger. No separate per-course trigger duplicates.
8. iPaaS parity: the public REST API is the integration surface. Zapier connects via OAuth; Make / n8n / Pipedream can use OAuth too (all three support it) or type: 'api' keys for raw HTTP. The Zapier app is packaging only — no Zapier-specific endpoints or payloads.
9. Repo location: apps/zapier. The Zapier app is a deployable that gets zapier push-ed to Zapier's cloud. Nothing else in the monorepo imports from it, so it sits next to apps/api and apps/dashboard rather than in packages/.
10. Revoke UX: per-grant revoke is available in the dashboard for the safety-net case (compromised Zapier account, employee offboarding). No bulk "Disconnect Zapier" button — customers managing their integration normally do so from inside Zapier.

Current-State Audit

Capability	Current State	Notes
Org-scoped automation keys	available	organization_api_key already supports type: 'mcp' | 'api' | 'zapier'. Rotation, revoke, last-used tracking all shipped. The 'zapier' value becomes unused under the OAuth model (see Technical Design).
Bearer auth middleware	available	automationKeyMiddleware + automationKeyScopesMiddleware in apps/api/src/middlewares/. Will be extended to also accept OAuth access tokens.
OAuth 2.0 server	missing	No OAuth authorization-code flow exists on the API. Required for v1.
OAuth consent screen	missing	No dashboard consent screen for third-party app authorization. Required for v1.
Public REST API	partial	/public-api/v1/courses and /public-api/v1/audience shipped. Tags, announcements, certificates, course clone, full audience update still missing.
Test-connection endpoint	missing	No GET /public-api/v1/me for Zapier's auth-test step.
Polling cursor / since filter	missing	List endpoints support page/limit but no ?since= or ?cursor= for stable Zapier polling.
Email/slug search filters	missing	Audience list does not accept ?email=; courses list does not accept ?slug= or ?title=.
Webhooks delivery	missing	prd/webhooks/README.md written but unshipped. Not a v1 dependency.
Dashboard Zapier tab	partial	/org/[slug]/automation/zapier route exists but renders a coming_soon callout. Will become an OAuth-grant management page, not a key-management page.
Automation usage tracking	available	organization_automation_usage already records read | write | publish per key. Will be extended to record per OAuth grant.
Plan gating utilities	available	MCP_AUTOMATION_LIMITS_BY_PLAN pattern in packages/utils/src/plans/automation.ts is the reference for Zapier rate limits.
Marketing positioning	partial	apps/website/src/routes/automation/+page.svelte advertises API + Webhooks + MCP. Does not yet mention Zapier.

Data Sources Checked

• packages/db/src/schema.ts (organization_api_key, organization_automation_usage)
• packages/utils/src/validation/organization/automation-key.ts
• packages/utils/src/validation/public-api/audience.ts
• packages/utils/src/validation/public-api/course.ts
• packages/utils/src/plans/automation.ts
• apps/api/src/middlewares/automation-key.ts
• apps/api/src/middlewares/automation-key-scopes.ts
• apps/api/src/routes/v1/courses.ts
• apps/api/src/routes/v1/audience.ts
• apps/api/src/services/v1/course.ts
• apps/api/src/services/v1/audience.ts
• apps/api/src/services/organization/automation-key.ts
• apps/api/src/services/course/{invite,people,certificate,completion,clone,compliance}.ts
• apps/api/src/services/submission/submission.ts
• apps/api/src/services/newsfeed/newsfeed.ts
• apps/api/src/services/tag.ts
• apps/dashboard/src/lib/features/automation/pages/{mcp,zapier}.svelte
• apps/website/src/routes/automation/+page.svelte
• prd/public-api [DONE]/README.md
• prd/webhooks/README.md

Product Goals

1. An org admin can connect ClassroomIO from inside Zapier in under 60 seconds without copying or pasting any token. The flow is: click Connect on Zapier → log into ClassroomIO → consent → done.
2. Non-engineering customers can build the three canonical Zaps without code:
   • CRM new customer → enroll in onboarding course.
   • Certificate issued → upload to HRIS / Drive.
   • Exercise submitted → notify tutor in Slack.
3. The Zapier app exposes a useful but small surface: 5 triggers, 5 actions, 2 searches in v1.
4. Same OAuth flow and REST endpoints work for Make, n8n, and Pipedream — they support OAuth natively, so no additional development is needed beyond the Zapier package.
5. Connected Zapier instances are visible to admins in the dashboard, with per-grant revoke for the safety-net case.
6. The integration is forward-compatible with webhooks: when REST Hooks become available, high-volume triggers (exercise submitted, lesson completed) upgrade with no UX change for the Zapier user.

Non-Goals (v1)

1. Public listing in the Zapier directory (deferred until v1 is validated with ~5 customers).
2. Real-time triggers via REST Hooks (deferred to v1.1, gated on prd/webhooks).
3. High-volume triggers (exercise.submitted, lesson.completed) that are impractical on polling.
4. Make / n8n / Pipedream apps as separate packaged listings (the REST API + OAuth supports them; no curated app yet).
5. Free / Basic plan access (gated to Early Adopter+).
6. Inbound webhooks from Zapier to ClassroomIO (Zapier writes via REST actions, not webhooks).
7. Monthly task credits or Zapier-specific credit budgets (Zapier is a binary plan feature; per-minute rate limits remain for abuse protection only).
8. Custom triggers / dynamic events authored by the customer.
9. PKCE / device-code / implicit OAuth grants (only authorization_code + refresh_token grants ship in v1).
10. OAuth dynamic client registration (Zapier is a hard-coded confidential client; other iPaaS vendors are added by hand in v1).
11. Bulk "Disconnect Zapier" button in the dashboard (customers disconnect from Zapier's side; admins use per-grant revoke for safety-net cases).
12. Branding review and Zapier marketplace screenshots (post-private validation).

User Stories

1. As an HR ops admin, I want a new hire in BambooHR to auto-enroll in the onboarding course so I don't manage a spreadsheet.
2. As a sales engineer, I want a HubSpot deal moving to "Customer" to enroll the buyer in the product training so onboarding starts on day zero.
3. As an L&D admin, I want every certificate.issued to upload a PDF to the employee's Google Drive folder so my audit trail lives in the source-of-truth.
4. As a tutor, I want every exercise.submitted for my course to DM me in Slack so I can grade quickly.
5. As a finance ops admin, I want every payment_request.created to create a HubSpot deal so I don't reconcile manually.
6. As an org admin, I want a Zapier-scoped key separate from my raw API keys so I can revoke Zapier without breaking my internal integrations.
7. As an org admin, I want my Zapier usage to count against the same plan limits as MCP and API so I'm not over-billed by tool sprawl.

UX Requirements

Dashboard Zapier Tab

Route: /org/[slug]/automation/zapier. Diverges from the MCP page because Zapier authenticates via OAuth grants, not bearer keys.

Required sections (top to bottom):

1. Admin permission callout for non-admin users.
2. Plan gating callout for orgs below Early Adopter — copy "Upgrade to Early Adopter to use Zapier" with an upgrade CTA. No connect flow visible.
3. "Connect on Zapier" CTA linking to the shared private invite URL (later the public listing).
4. Connected Zapier instances table — one row per active OAuth grant. Columns: label (e.g. "Zapier — workspace abc.com"), scopes (read / read+write), last used, connected at, status. Row action: revoke.
5. Rate limit summary — current per-minute read and write caps for the org's plan.
6. Setup guide — step-by-step screenshots of the Connect flow from inside Zapier (click Connect → log in → consent → done).
7. Docs callout linking to apps/docs Zapier guide.

Reuse where possible:

• Read OAuth grants and usage via a new automationOauth.svelte.ts API class in apps/dashboard/src/lib/features/automation/api/.
• Shared types live in apps/dashboard/src/lib/features/automation/utils/types.ts.
• Replace the current placeholder in apps/dashboard/src/lib/features/automation/pages/zapier.svelte.

Consent Screen

Route: /oauth/consent in the dashboard. Triggered by Zapier's authorize redirect.

Behavior:

1. If the user is not logged in, redirect to the existing login flow with a redirect_to=/oauth/consent?... parameter so they return here after auth.
2. Render the consenting org's name, the requesting app (Zapier), the requested scopes (zapier:read, zapier:write), and the redirect URI.
3. For multi-org users, show an org picker — only orgs where the user is admin AND the plan is Early Adopter+ appear.
4. Show two buttons: Authorize and Deny. On Authorize, the dashboard POSTs to the API to issue an authorization code, then redirects to Zapier's callback with ?code=…&state=…. On Deny, redirects to Zapier's callback with ?error=access_denied&state=….
5. Admins can untick zapier:write on the consent screen to grant a read-only connection.

Zapier App UX

The Zapier app surface, as seen by a Zap author:

• App name: ClassroomIO
• Auth flow: OAuth 2.0. User clicks Connect in Zapier → Zapier opens our /oauth/authorize URL → user logs in (if needed) and consents → redirected back to Zapier with a code → Zapier exchanges for tokens silently. No copy-paste.
• Test step: after token exchange, Zapier calls GET /public-api/v1/me with the new access token. Shows {org.name} on Zapier's connections page.
• Trigger picker lists the 5 triggers below with one-line descriptions matching the website's voice.
• Action picker lists the 5 actions below.
• Search picker lists the 2 searches below.
• Dynamic dropdowns:
  • Course dropdown is powered by GET /public-api/v1/courses?fields=id,title&limit=100.
  • Tag dropdown is powered by GET /public-api/v1/tags?limit=100 (new endpoint, see Technical Design).
• Sample data: every trigger ships a static sample record so Zap authors can build downstream steps without firing a real event.
• Token refresh: the Zapier app uses Zapier's built-in refresh_token handling — Zapier auto-refreshes access tokens via our /oauth/token endpoint when they expire.

Marketing Surface

Update apps/website/src/routes/automation/+page.svelte and the home page automation band to mention Zapier alongside REST API + Webhooks + MCP. Add a Connect via Zapier row to the integrations section. Update the automate-section.svelte copy to name Zapier explicitly ("New hire joins BambooHR → enrolled via Zapier").

This marketing work is a follow-up PR after the integration is private-listed. Tracked in this PRD but does not gate v1 ship.

Trigger Catalog (v1)

All triggers ship as polling. Each trigger emits createdAt-ordered records and dedupes by id on the Zapier side.

Trigger	Description	Source endpoint	Optional filters
new_audience_member	New student added to the organization audience	GET /public-api/v1/audience?sortBy=createdAt&sortOrder=desc	none
student_enrolled_in_course	A student was added to a course (invite accepted or direct add)	GET /public-api/v1/audience/enrollments?sortBy=createdAt&sortOrder=desc (new)	courseId, tagId
course_completed	A student completed all required lessons in a course	GET /public-api/v1/course-completions?sortBy=completedAt&sortOrder=desc (new)	courseId, tagId
certificate_issued	A certificate was issued for a learner	GET /public-api/v1/certificates?sortBy=issuedAt&sortOrder=desc (new)	courseId
payment_request_created	A learner submitted a payment request form	GET /public-api/v1/payment-requests?sortBy=createdAt&sortOrder=desc (new)	courseId

Deferred to v1.1 (require webhooks for sane volume / latency):

• exercise_submitted
• exercise_graded
• lesson_completed
• newsfeed_post_created
• community_question_created
• compliance_course_overdue

Deferred to v2 (no current customer ask):

• program_completed

Action Catalog (v1)

Each action is a thin Zapier wrapper over an existing or new public API write endpoint.

Action	Description	Endpoint	Scope
enroll_student_in_course	Find-or-create the student by email and assign to one or more courses	POST /public-api/v1/audience + POST /public-api/v1/audience/assign-courses	zapier:write
add_student	Create an audience member without course assignment	POST /public-api/v1/audience	zapier:write
update_student	Update audience member profile (name, email, custom attributes)	PUT /public-api/v1/audience/:memberId (extend payload schema)	zapier:write
remove_student	Remove a student from the organization	DELETE /public-api/v1/audience/:memberId	zapier:write
tag_student	Apply or remove a tag on an audience member	POST /public-api/v1/audience/:memberId/tags (new)	zapier:write

Deferred to v1.1 (need new public API routes that aren't critical-path):

• send_announcement (newsfeed post)
• issue_certificate
• clone_course_from_template
• publish_course_draft (already an MCP tool; trivial to expose later)
• create_payment_request

Search Catalog (v1)

Search	Description	Endpoint
find_student_by_email	Look up audience member by exact email	GET /public-api/v1/audience?email=… (new filter)
find_course	Look up a course by slug or title	GET /public-api/v1/courses?slug=… or ?title=… (new filters)

Both searches power Zapier's find-or-create pattern; together with the create actions, Zapier auto-generates "Find or Create Student" and "Find or Create Course" steps with no extra Zapier app code.

Authentication and Scopes

OAuth 2.0 server (new)

Implement the authorization_code + refresh_token grants from RFC 6749 only. No PKCE, implicit, device, or client_credentials grants in v1. Zapier is registered as a single confidential OAuth client.

Endpoints (hosted on the API):

Endpoint	Method	Purpose
/oauth/authorize	GET	Validates client_id, redirect_uri, response_type=code, scope, state. Redirects the browser to the dashboard consent screen /oauth/consent.
/oauth/authorize/issue	POST	Called by the dashboard consent screen after the admin clicks Authorize. Issues a single-use authorization code (TTL 60 seconds) bound to org_id, client_id, scopes, redirect_uri, and the consenting user. Returns the code to the dashboard, which redirects the browser to redirect_uri?code=…&state=….
/oauth/token	POST	Exchanges an authorization code for an access token (TTL 1 hour) + refresh token (TTL 90 days). Also handles grant_type=refresh_token.
/oauth/revoke	POST	Revokes an access or refresh token (RFC 7009).

Library choice: lean on oauth4webapi or roll a minimal implementation. The scope is narrow enough that hand-rolling is reasonable; pick during implementation kickoff.

OAuth client registration

Zapier client credentials are stored as environment variables, not in the database, in v1:

• ZAPIER_OAUTH_CLIENT_ID
• ZAPIER_OAUTH_CLIENT_SECRET
• ZAPIER_OAUTH_REDIRECT_URIS (comma-separated list of allowed callbacks from Zapier's docs)

A packages/utils/src/oauth/clients.ts resolver returns the registered clients keyed by client_id. Adding Make / n8n / Pipedream later is a config-only change.

Token storage

New tables (see Technical Design):

• oauth_authorization_code — short-lived single-use codes.
• oauth_access_token — hashed Bearer tokens.
• oauth_refresh_token — hashed long-lived tokens.

Every token row carries: id, client_id, organization_id, granted_by_profile_id, scopes, created_at, expires_at, revoked_at, last_used_at.

Middleware integration

Extend automationKeyMiddleware to a unified bearerAuthMiddleware that:

1. Reads Authorization: Bearer ….
2. Tries to resolve the token as an OAuth access token (hash-and-lookup against oauth_access_token). If found and not expired or revoked, sets c.set('orgId'), c.set('actorId', granted_by_profile_id), c.set('authSource', 'oauth'), c.set('scopes', grant.scopes).
3. Falls back to the existing automation-key path (organization_api_key) for type: 'api' / type: 'mcp' consumers.
4. Returns 401 if neither path matches.

This means existing API keys keep working unchanged for Make / n8n / Pipedream users who prefer raw bearer tokens. Zapier-only consumers go through OAuth.

Scopes

Two OAuth scopes:

• zapier:read — list, get, search on courses, audience, submissions, certificates, tags, completions, payment requests.
• zapier:write — create, update, delete on audience, course assignments, tags.

Scope-to-route map:

Endpoint	Required scopes (OAuth)	Required scopes (API key fallback)
GET /public-api/v1/me	zapier:read	public_api:*
All GET /public-api/v1/* triggers and searches	zapier:read	public_api:*
Audience / course / tag write endpoints	zapier:write	public_api:*

automationKeyScopesMiddleware is extended to check whichever scope set applies based on c.get('authSource').

Dropping type: 'zapier' from API key types

Under the OAuth model, the dashboard never issues Zapier API keys. Update ZOrganizationApiKeyType in packages/utils/src/validation/organization/automation-key.ts to remove 'zapier'. Existing rows are zero (the dashboard tab has always been a placeholder), so no migration is needed beyond the schema/enum change.

Polling Contract

Every list endpoint exposed to Zapier triggers must guarantee:

1. Stable sort: sortBy and sortOrder defaulted to newest-first.
2. Stable record ID: each record returns an id that does not change across pages.
3. since cursor: accept an optional ?since=<ISO-8601> query parameter so Zapier can request only records newer than the highest createdAt it has already seen. If since is absent, return the most recent page only.
4. limit <= 100 with a default of 50.
5. Idempotent: identical query returns identical results within the polling window.

Zapier polls every 1–15 minutes depending on the customer's Zapier plan. Our endpoints must remain cheap to poll under that cadence.

Future REST Hooks Upgrade Path

When prd/webhooks/README.md ships, we add to the Zapier app:

1. Replace the existing subscribe / unsubscribe no-ops with calls to the webhook management API (POST /organization/webhooks with a Zapier-managed endpoint).
2. Move the high-volume triggers (exercise_submitted, lesson_completed, newsfeed_post_created) to REST Hook mode and ship them in v1.1.
3. Keep the existing polling triggers as a fallback when the webhook URL is unreachable.

This is a Zapier-app-only change in v1.1 — the public API surface does not change shape.

Plan Gating

Zapier is a binary plan feature. No monthly credit budgets.

Add ZAPIER_AUTOMATION_LIMITS_BY_PLAN to packages/utils/src/plans/automation.ts:

Plan	Zapier enabled	Max active grants	Per-org reads / min	Per-org writes / min
Basic	no	0	0	0
Early Adopter	yes	5	120	40
Enterprise	yes	25	360	120

Enforcement points:

1. At /oauth/authorize: reject the request with error=access_denied if the consenting org's plan does not include Zapier, or if max active grants is already reached.
2. At bearerAuthMiddleware for OAuth tokens: reject with 403 + code: PLAN_GATED if the org's plan has dropped below Early Adopter since the grant was issued.
3. At route entry: rate-limit against the per-minute caps using the existing rate-limiter middleware, keyed by (org_id, scope_category).

Usage tracking: every Zapier API call still increments organization_automation_usage with category read or write for visibility, but no credits are deducted.

Plan downgrade flow:

1. The plan-change service emits an internal event organization.plan.changed.
2. A handler in apps/api/src/services/oauth/ checks whether the new plan disables Zapier.
3. If yes, revoke all active OAuth grants for the org by setting revoked_at on every related access and refresh token.
4. The dashboard Zapier tab then shows the plan-gating callout with an upgrade CTA.

Basic / free plan users still see the dashboard Zapier tab so they understand the feature exists. The Connect CTA is replaced by an upgrade CTA. No connect link is rendered.

Technical Design

Schema additions

In packages/db/src/schema.ts:

1. oauth_authorization_code
   • id (UUID, primary)
   • code_hash (string, indexed unique)
   • client_id (string)
   • organization_id (UUID, FK)
   • granted_by_profile_id (UUID, FK)
   • redirect_uri (string)
   • scopes (text[])
   • created_at, expires_at (60 s TTL)
   • consumed_at (nullable; codes are single-use)
2. oauth_access_token
   • id (UUID, primary)
   • token_hash (string, indexed unique)
   • token_prefix (first 6 chars for dashboard display)
   • client_id
   • organization_id (FK)
   • granted_by_profile_id (FK)
   • refresh_token_id (FK to oauth_refresh_token)
   • scopes
   • created_at, expires_at (1 h TTL)
   • revoked_at, last_used_at
3. oauth_refresh_token
   • id (UUID, primary)
   • token_hash (string, indexed unique)
   • client_id
   • organization_id (FK)
   • granted_by_profile_id (FK)
   • scopes
   • label (e.g., "Zapier — workspace abc.com" — derived from the Zapier callback URI host)
   • created_at, expires_at (90 d TTL, sliding)
   • revoked_at, last_used_at

Remove 'zapier' from the organization_api_key.type enum (no migration since no rows use it).

Validation Layer

Add new files:

• packages/utils/src/validation/oauth/oauth.ts — ZOauthAuthorizeQuery, ZOauthIssueCodeBody, ZOauthTokenBody, ZOauthRevokeBody, ZOauthScope.
• packages/utils/src/validation/public-api/tag.ts
• packages/utils/src/validation/public-api/me.ts
• packages/utils/src/validation/public-api/enrollments.ts
• packages/utils/src/validation/public-api/completions.ts
• packages/utils/src/validation/public-api/certificates.ts
• packages/utils/src/validation/public-api/payment-requests.ts

Extend:

• packages/utils/src/validation/public-api/audience.ts — accept email filter on ZPublicApiAudienceQuery and broaden ZPublicApiUpdateAudience to support full profile (name, locale, custom attributes).
• packages/utils/src/validation/public-api/course.ts — accept slug and title filters on the list query.
• packages/utils/src/validation/organization/automation-key.ts — remove 'zapier' from ZOrganizationApiKeyType. The 'zapier:read' / 'zapier:write' scope strings live in the new OAuth scope enum, not in the automation-key scope enum.

Query Layer

Add:

• packages/db/src/queries/oauth/authorization-code.ts — issue, consume, expire.
• packages/db/src/queries/oauth/access-token.ts — issue, lookup by hash, revoke, touch last_used_at.
• packages/db/src/queries/oauth/refresh-token.ts — issue, lookup by hash, revoke, list active grants per org.
• packages/db/src/queries/course/completions.ts — list completions ordered by completedAt with since cursor.
• packages/db/src/queries/course/certificates.ts — list issued certificates with since cursor.
• packages/db/src/queries/course/payment-requests.ts — list payment requests with since cursor.
• packages/db/src/queries/organization/me.ts — read org + grant metadata for the test-connection endpoint.

Service Layer

New services:

• apps/api/src/services/oauth/clients.ts — load Zapier client config from env.
• apps/api/src/services/oauth/authorize.ts — validate authorize request, issue code on consent.
• apps/api/src/services/oauth/token.ts — exchange code for tokens, refresh tokens.
• apps/api/src/services/oauth/revoke.ts — revoke tokens.
• apps/api/src/services/oauth/plan-guard.ts — revoke all grants when an org drops below Early Adopter.
• apps/api/src/services/v1/me.ts
• apps/api/src/services/v1/tag.ts
• apps/api/src/services/v1/enrollments.ts
• apps/api/src/services/v1/completions.ts
• apps/api/src/services/v1/certificates.ts
• apps/api/src/services/v1/payment-requests.ts

Extend apps/api/src/services/v1/audience.ts to handle the broadened update payload and the tag/untag action.

Wire oauth/plan-guard.ts into the existing plan-change pathway in apps/api/src/services/license.ts so downgrades immediately revoke grants.

Middleware Layer

• New: rename automationKeyMiddleware to bearerAuthMiddleware (or wrap it) so it tries OAuth tokens first, then falls back to organization_api_key.
• Extend automationKeyScopesMiddleware to honor c.get('authSource') and check OAuth scopes vs API-key scopes accordingly.

Route Layer

New OAuth routes (mounted at the API root, not under /public-api):

• GET /oauth/authorize
• POST /oauth/authorize/issue (called by the dashboard consent screen with session auth, not bearer)
• POST /oauth/token
• POST /oauth/revoke

New public API routes (all under /public-api/v1):

• GET /public-api/v1/me
• GET /public-api/v1/audience/enrollments
• GET /public-api/v1/course-completions
• GET /public-api/v1/certificates
• GET /public-api/v1/payment-requests
• GET /public-api/v1/tags
• POST /public-api/v1/audience/:memberId/tags
• DELETE /public-api/v1/audience/:memberId/tags/:tagId

Public API routes follow the existing v1 pattern: bearerAuthMiddleware + automationKeyScopesMiddleware + describeRoute + validator. Each route returns a single response type per the routing rules in AGENTS.md.

Dashboard Routes

New routes:

• apps/dashboard/src/routes/(app)/oauth/consent/+page.svelte — consent screen.
• apps/dashboard/src/routes/(app)/oauth/consent/+page.server.ts — load consent context (client, scopes, redirect URI, eligible orgs).

Replace:

• apps/dashboard/src/lib/features/automation/pages/zapier.svelte — new OAuth grant management page.
• apps/dashboard/src/routes/(app)/org/[slug]/zapier/+page.svelte and any associated +page.server.ts — hydrate grants list and rate-limit data.

New API class:

• apps/dashboard/src/lib/features/automation/api/automation-oauth.svelte.ts — list grants, revoke a grant, consent action.

Zapier App (apps/zapier)

New workspace package:

apps/zapier/
├── package.json
├── tsconfig.json
├── index.ts                    # Zapier app entry
├── authentication.ts
├── triggers/
│   ├── new-audience-member.ts
│   ├── student-enrolled.ts
│   ├── course-completed.ts
│   ├── certificate-issued.ts
│   ├── payment-request-created.ts
│   └── program-completed.ts
├── creates/                    # Zapier name for "actions"
│   ├── enroll-student-in-course.ts
│   ├── add-student.ts
│   ├── update-student.ts
│   ├── remove-student.ts
│   └── tag-student.ts
├── searches/
│   ├── find-student-by-email.ts
│   └── find-course.ts
├── utils/
│   └── client.ts              # shared fetch wrapper, base URL, headers
└── test/
    └── *.test.ts

Dependencies (not introduced into root):

• zapier-platform-core (Zapier-required runtime).
• @cio/utils for typed payload schemas via workspace protocol.

Build/release flow:

• pnpm --filter @cio/zapier build — typechecks the app.
• pnpm --filter @cio/zapier zapier:push — uploads to Zapier under a private app version.
• pnpm --filter @cio/zapier zapier:promote — manual step to promote a tested version.

No CI auto-push. Promotion is a manual step gated on the on-call engineer.

API and Docs

1. Every new /public-api/v1/* route added under this PRD is annotated with describeRoute so it lands in the existing OpenAPI generator.
2. Run pnpm --filter @cio/api upload:openapi after route additions.
3. Add a Zapier guide in apps/docs:
   • Connecting your account (create key in dashboard, paste in Zapier).
   • Trigger catalog with sample payloads.
   • Action catalog with required fields.
   • Search catalog.
   • Rate limits and plan limits.
   • Troubleshooting (key revoked, scope missing, plan downgrade).
4. Update apps/website/src/routes/automation/+page.svelte to add a Zapier section alongside REST API + Webhooks + MCP. Include the canonical Zaps as copy.
5. Add a Connect on Zapier button to apps/website/src/lib/components/automate-section.svelte.

Rollout Plan

Phase 1: OAuth server foundation

1. Schema: oauth_authorization_code, oauth_access_token, oauth_refresh_token.
2. Queries, services, validation for OAuth.
3. Routes: /oauth/authorize, /oauth/authorize/issue, /oauth/token, /oauth/revoke.
4. Extend bearerAuthMiddleware to resolve OAuth tokens before falling back to automation keys.
5. Add zapier:read / zapier:write scope enforcement to automationKeyScopesMiddleware.
6. Plan-guard hook into license.ts for downgrade revocation.
7. Drop 'zapier' from organization_api_key.type enum.

Phase 2: Consent screen + dashboard

1. Build /oauth/consent page in the dashboard with org picker, scope-edit, Authorize / Deny.
2. Replace pages/zapier.svelte placeholder with the OAuth grant management page.
3. Add automation.zapier.* translations (followed by pnpm translate).
4. Plan-gating callout for Basic plan.

Phase 3: Public API surface

1. Add GET /public-api/v1/me.
2. Extend audience update payload + add ?email= filter.
3. Add course list ?slug= / ?title= filters.
4. Add tag list + tag/untag audience endpoints.
5. Add enrollments, course-completions, certificates, payment-requests list endpoints with ?since= cursors.
6. Build and upload OpenAPI spec.

Phase 4: Zapier app

1. Scaffold apps/zapier with zapier-platform-core configured for OAuth 2.0.
2. Implement triggers, creates, searches against the public API.
3. Add dynamic dropdowns powered by /courses and /tags.
4. Add sample data for each trigger.
5. zapier push private app version 1.0.0.

Phase 5: Private validation

1. Distribute the shared private invite URL to paying orgs.
2. Collect usage data via organization_automation_usage.
3. Iterate on copy, scopes UX, and field defaults based on Zap author feedback.
4. Update docs and marketing.

Phase 6: Public listing

1. Submit to Zapier directory review.
2. Promote app version once approved.
3. Update marketing site and announce.

Phase 7 (v1.1): REST Hooks upgrade

1. Wait for prd/webhooks ship.
2. Wire subscribe / unsubscribe to the webhook management API.
3. Promote exercise_submitted, lesson_completed, newsfeed_post_created to instant triggers.

Phase 8 (v2): Programs, more actions, more iPaaS apps

1. Add program_completed trigger and apps/zapier integration.
2. Add send_announcement, issue_certificate, clone_course_from_template, publish_course_draft, create_payment_request actions.
3. Register Make / n8n / Pipedream as additional OAuth clients (config-only).
4. Consider native Make and Pipedream packages if customers ask.

Success Metrics

1. = 5 orgs connect a Zapier key within 30 days of private invite.

2. = 100 Zap runs/week within 60 days of private invite.

3. p95 trigger latency under 5 minutes on the Early Adopter plan (Zapier polling cadence).
4. < 2% of Zap runs fail due to API errors (excluding user misconfiguration).

5. = 80% of connected orgs use at least one trigger and one action (i.e., the integration is bidirectional, not one-way data export).

6. Zero security incidents related to leaked or misused Zapier keys.

Risks and Mitigations

1. OAuth server is a new attack surface.
   • Mitigation: keep the implementation minimal (authorization_code + refresh_token only). Hash tokens at rest. Single-use authorization codes with 60-second TTL. Server-side scope validation. Add OAuth-specific security tests. Run a security review of the implementation before public listing.
2. Polling latency dissatisfies customers expecting real-time.
   • Mitigation: set expectation in dashboard and docs ("delivered within ~5 minutes on polling, instant after webhooks v1.1"). Prioritize webhooks PRD ship.
3. exercise_submitted demand on polling.
   • Mitigation: do not ship it in v1. Document that it lands with v1.1 / webhooks.
4. Zapier's marketplace review rejects public listing.
   • Mitigation: stay private until v1 is polished. Use private validation period to fix UX issues Zapier reviewers commonly flag (sample data, error messages, dropdown UX, OAuth flow edge cases).
5. Plan gating frustrates Basic users who see the tab but cannot use it.
   • Mitigation: clear upgrade CTA copy, and a docs link explaining why Zapier sits on Early Adopter+.
6. Plan downgrade silently revokes grants and breaks live Zaps.
   • Mitigation: surface a banner in the dashboard 7 days before a known billing-driven downgrade fires (where the billing system gives notice). For immediate downgrades, send a notification email naming each revoked grant and the Zaps that may be affected.
7. Drift between Zapier app schema and public API schema.
   • Mitigation: apps/zapier consumes types from @cio/utils/validation/public-api directly so a schema change at the API breaks the Zapier build at CI time.
8. Shared private invite URL leaks publicly.
   • Mitigation: enforce plan gating at the /oauth/authorize step regardless of who clicks Connect. Leakage of the invite URL is harmless because the OAuth flow still verifies the user is an admin of an Early Adopter+ org.

Build and Verification Commands

1. pnpm --filter @cio/utils build
2. pnpm --filter @cio/db build
3. pnpm --filter @cio/api build
4. pnpm --filter @cio/api upload:openapi
5. pnpm --filter @cio/dashboard build
6. pnpm --filter @cio/zapier build
7. pnpm --filter @cio/zapier zapier:push (manual, gated)

Manual verification:

1. Install the Zapier app via the private invite URL while logged out — confirm Zapier prompts for ClassroomIO login during the OAuth handshake.
2. Complete the OAuth flow as an org admin on Early Adopter — confirm Test Connection in Zapier shows the org name returned by GET /public-api/v1/me.
3. Try the OAuth flow as a non-admin of the same org — confirm Authorize is hidden or disabled and Deny redirects with error=access_denied.
4. Try the OAuth flow on a Basic-plan org — confirm /oauth/authorize rejects with the upgrade CTA visible.
5. Untick zapier:write on the consent screen — confirm the resulting token only allows read endpoints and 403s on write endpoints.
6. Build a Zap: New audience member → Slack message. Trigger by adding an audience member; receive Slack message within 5 minutes.
7. Build a Zap: HubSpot deal → Enroll student in course. Add a deal; confirm the audience member appears and is assigned.
8. Build a Zap: Certificate issued → Google Drive upload. Issue a cert; confirm the file appears.
9. Revoke the grant from the dashboard; confirm all three Zaps surface authentication errors on next run and Zapier shows a re-connect prompt.
10. Downgrade the org to Basic; confirm the dashboard tab shows the upgrade CTA, the existing grants are revoked immediately, and Zaps fail with a PLAN_GATED error.
11. Force an access token expiry; confirm Zapier transparently refreshes via /oauth/token without user interaction.

Open Questions

1. Should we use oauth4webapi (lighter, OAuth-spec-compliant), node-oauth2-server (heavier but battle-tested), or hand-roll the minimal authorization_code + refresh_token grants? Decide at implementation kickoff.
2. Refresh-token rotation strategy: rotate on every refresh (safer, more complex) or keep the same refresh token across refreshes (simpler, Zapier-compatible)? Zapier supports both — confirm with Zapier docs during build.
3. Should the consent screen support cross-org consent in a single screen (one Zapier connection covers multiple orgs), or strictly one OAuth grant per org? v1 is one grant per org; cross-org is a v2 question if multi-org admins ask for it.
4. Where do we display last_used_at for a grant? Inside the dashboard grants table only, or also in an email digest? v1 is dashboard-only.
5. Do we expose any OAuth telemetry (token issue / refresh / revoke counts) to the internal admin tooling, or rely on database queries on demand?