Copy page

Advanced Topics

OAuth

Extension apps get two independent OAuth capabilities on a single app registration — pick either or both depending on what your app needs:

• install — install-integrated OAuth. Every install auto-mints an org-scoped access token + refresh token, delivered to your backend inside the app.installed webhook. No browser step; the Install click IS the grant. Use this for background integrations that call the Teachfloor API without any specific user in the loop (nightly sync, event-triggered updates, admin dashboards).
• authorize — classic OAuth 2.0 authorization-code flow. A user signs in via Teachfloor's /oauth/authorize, your app receives a code, exchanges it for tokens. Add the openid scope and it becomes full OpenID Connect (id_token identifying the user) — perfect for "Sign in with Teachfloor" flows in your app's UI.

Both flows share the SAME client_id + client_secret. Configure one, both, or none — the manifest tells Teachfloor which behaviors to enable.

This chapter covers both capabilities: opting in, receiving credentials, making API calls, refreshing tokens, silent sign-in, and revocation.

What you can build

With install:

• Backend integrations that read platform data — sync course completions to your HR system, mirror members to your CRM, ingest activity streams into your data warehouse.
• Automated workflows — poll the API from your backend on your own schedule, augmenting the push-based webhook data.

With authorize:

• Sign in with Teachfloor on your own web UI — users click a button, get redirected to Teachfloor, land back on your app already signed in.
• Silent sign-in on post-install redirect — after a user installs your app, drop them onto your setup page already signed in (no re-authentication).

If you only need in-app data access (from within your app's dashboard view), the SDK's teachfloor.get(...) helpers already do that. OAuth is for anything OUTSIDE the dashboard — your backend, your own web UI, external integrations.

How it works

install flow — When an organization installs your app, Teachfloor mints an access token + refresh token bound to that installation and delivers them inside the app.installed webhook payload. Your backend stores the tokens per-installation and uses them as bearer tokens against https://api.teachfloor.com/v0/*.

authorize flow — Your app redirects the user's browser to https://app.teachfloor.com/oauth/authorize?client_id=...&scope=openid+profile+email&redirect_uri=.... The user consents (or silent-approves if you use prompt=none), Teachfloor redirects to your callback with a code, your backend exchanges the code at /oauth/token for tokens including an id_token identifying the user.

One client_id + client_secret pair identifies your app across every organization that installs it; each install then gets its own access_token and refresh_token. The client_id + client_secret are shown to you once at app creation (via the CLI and the Developer dashboard) — store them in your app config; they never appear in webhook payloads.

Opt in

The oauth manifest block declares which capabilities your app wants. Pick either or both:

Install-integrated (background API access):

Code
"oauth": { "install": true }

Authorize flow with OIDC (user sign-in):

Code
"oauth": {
  "authorize": {
    "redirect_uris": [
      "https://my-app.com/oauth/callback",
      "http://localhost:3000/oauth/callback"
    ]
  }
}

Hybrid (both — same app, same client credentials):

Code
"oauth": {
  "install": true,
  "authorize": {
    "redirect_uris": ["https://my-app.com/oauth/callback"]
  }
}

Full manifest example (hybrid):

Code
{
  "id": "my-app",
  "name": "My App",
  "version": "1.0.0",
  "oauth": {
    "install": true,
    "authorize": {
      "redirect_uris": ["https://my-app.com/oauth/callback"]
    }
  },
  "permissions": [
    { "permission": "courses:read", "purpose": "Sync course completions to our HR tool" },
    { "permission": "modules:read", "purpose": "Attribute completions to the right module" },
    { "permission": "openid",       "purpose": "Sign you in to My App using your Teachfloor account" },
    { "permission": "profile",      "purpose": "Show your name on your My App dashboard" },
    { "permission": "email",        "purpose": "Contact you about integration issues" }
  ],
  "webhook": {
    "url": "https://my-app.com/teachfloor/webhook",
    "events": ["course.completed"]
  }
}

Fields:

Field	Required	Rules
oauth.install	no	Must be the literal boolean true when present. Enables install-integrated tokens delivered via webhook.
oauth.authorize	no	Object with redirect_uris when present. Enables browser code flow at /oauth/authorize.
oauth.authorize.redirect_uris	yes (when authorize block present)	Array of one or more https:// callback URLs. http://localhost / http://127.0.0.1 / http://[::1] allowed for local dev per RFC 8252.

At least one of install or authorize must be declared when the oauth block is present.

Additional requirements per capability

For install:

• A webhook block — credentials arrive inside the app.installed webhook, so if there's no webhook endpoint, there's nowhere to deliver them.
• At least one permission that maps to an OAuth scope (see the permission mapping table).

For authorize:

• OIDC identity permissions in your permissions array — declare which claims your app is allowed to request. Requests for scopes not in your manifest are rejected with invalid_scope. Minimum for basic sign-in: openid. Add profile for the user's name, email for their email address.

Permission → scope mapping

Adding a permission to the manifest allows your app to request the matching OAuth scope — no separate scope declaration needed. Permissions split into two categories by flow:

Grantable on install tokens (delivered via app.installed webhook, org-scoped, hit the public API):

Manifest permission	OAuth scope	Grants
courses:read	courses:read	GET /v0/courses/*
modules:read	modules:read	GET /v0/modules/*
elements:read	elements:read	GET /v0/elements/*
members:read	members:read	GET /v0/members/*, GET /v0/courses/{id}/members/*
activities:read	activities:read	GET /v0/activities/*, GET /v0/elements/{id}/activities

Grantable on authorize tokens (delivered via /oauth/token code exchange, user-scoped, populate id_token claims):

Manifest permission	OAuth scope	Delivered claim in id_token
openid	openid	sub (stable user id), iss, aud, iat, exp (base claims — always present when openid is granted)
profile	profile	name
email	email	email, email_verified

These two sets are mutually exclusive per token flow: install tokens can't carry identity claims; authorize tokens can't reach the public API. If your app needs both, declare install: true AND authorize: {...} in the manifest and use each flow for its intended purpose.

Other manifest permissions (data storage, realtime, AI, etc.) are SDK-only — they don't map to any OAuth scope and don't appear on issued tokens.

Receiving credentials

Credentials arrive in the data.credentials block of the app.installed webhook. See the Webhooks chapter for the full envelope.

Code
{
  "type": "app.installed",
  "data": {
    "organization": { "id": "acme-corp", "name": "Acme Corp" },
    "installer":    { "id": "usr_...", "email": "alice@acme.com", "full_name": "Alice Doe" },
    "credentials": {
      "client_id":     "9f8e7d6c-...",
      "access_token":  "eyJhbGc...",
      "refresh_token": "def50200...",
      "expires_at":    "2026-08-25T14:32:01+00:00",
      "token_type":    "Bearer",
      "scope":         "courses:read modules:read"
    }
  }
}

Store access_token and refresh_token per-install (keyed by organization.id) — you'll need both for API calls and for the refresh flow. Combine them at refresh time with the client_id + client_secret you already have in your app config from when you created the app.

The client_secret is not in this payload. Fetch it once from the Teachfloor developer dashboard (Developers → Apps → your app → OAuth Client Secret) or from the teachfloor apps create CLI response, and store it in your app config — it's the same across every install of your app, so per-install storage isn't required.

Recommended per-install storage shape:

Code
CREATE TABLE teachfloor_installations (
  organization_id  VARCHAR(255) PRIMARY KEY,   -- from data.organization.id
  installer_email  VARCHAR(255),               -- from data.installer.email
  client_id        VARCHAR(255) NOT NULL,      -- from data.credentials.client_id
  access_token     TEXT NOT NULL,
  refresh_token    TEXT NOT NULL,
  expires_at       TIMESTAMP NOT NULL,
  scopes           TEXT NOT NULL,
  installed_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Keep client_secret in your app-level config (env var, secrets manager), NOT per-install.

Treat all four values as sensitive. Don't log them to any observability tool that might retain them, and redact them from error reports.

Auto-provisioning users on install

The installer block identifies the user who clicked Install — always present, whether or not the app opted into OAuth. Use it to auto-provision an account on your side BEFORE the user's browser arrives at your post-install landing page:

Code
// Inside your webhook handler for app.installed
async function handleAppInstalled(event) {
  const { organization, installer, credentials } = event.data

  // Provision or match an account for the installer.
  const user = await findOrCreateUser({
    email:    installer.email,
    name:     installer.full_name,
    externalId: installer.id,
  })

  // Store the OAuth credentials keyed by org.
  if (credentials) {
    await saveInstallation({
      organizationId: organization.id,
      installerEmail: installer.email,
      ...credentials,
    })
  }

  // Optionally sign the user in via a magic link so their post-install
  // redirect lands in a signed-in state.
  await sendMagicLink(user, { redirectUrl: '/dashboard' })
}

By the time the user's browser arrives at your post-install redirect URL, their account exists on your side. Match them to the installation by email and drop them into a signed-in experience — no sign-up form.

Install delivery timing

The app.installed webhook lands at your backend before the browser follows the post-install redirect. Your landing page can rely on the installation already being provisioned on your side (credentials stored, user auto-provisioned).

To make that guarantee your endpoint has a 3-second window to ack. If you respond in time, the redirect fires only after your ack. If you don't (slow, down, error), the install still succeeds and the webhook is retried on the standard schedule — the redirect proceeds and your landing page falls back to your normal sign-up flow.

Practical implication: keep your app.installed handler fast. Store the credentials, provision a user, ack with 200. Anything heavy (email dispatch, external API calls, analytics) should happen in a background job after the ack.

Making API calls

Bearer-authenticate with the access_token:

Code
curl https://api.teachfloor.com/v0/courses \
  -H "Authorization: Bearer eyJhbGc..."

Every request must include the token. The token grants access scoped to:

• The organization that installed the app — you can only reach that org's data.
• The scopes declared in the token — a token with only courses:read can call GET /v0/courses/* but gets 403 on GET /v0/members.

If a request returns 401, the token has expired or been revoked — refresh it. If it returns 403 Insufficient scope, the token doesn't have permission for that endpoint (your manifest didn't declare a mapping permission).

Node.js:

Code
const fetch = require('node-fetch')

async function getCourses(installation) {
  let accessToken = installation.access_token
  if (Date.parse(installation.expires_at) < Date.now() + 60_000) {
    // Refresh proactively if we're within 60s of expiry.
    ({ access_token: accessToken } = await refreshToken(installation))
  }

  const res = await fetch('https://api.teachfloor.com/v0/courses', {
    headers: { 'Authorization': `Bearer ${accessToken}` },
  })

  if (res.status === 401) {
    // Expired between our check and the request — refresh once and retry.
    const { access_token: fresh } = await refreshToken(installation)
    return fetch('https://api.teachfloor.com/v0/courses', {
      headers: { 'Authorization': `Bearer ${fresh}` },
    }).then(r => r.json())
  }

  return res.json()
}

Python:

Code
import requests
from datetime import datetime, timezone, timedelta

def get_courses(installation):
    access_token = installation["access_token"]
    expires_at = datetime.fromisoformat(installation["expires_at"])
    if expires_at < datetime.now(timezone.utc) + timedelta(seconds=60):
        access_token = refresh_token(installation)["access_token"]

    r = requests.get(
        "https://api.teachfloor.com/v0/courses",
        headers={"Authorization": f"Bearer {access_token}"},
    )

    if r.status_code == 401:
        access_token = refresh_token(installation)["access_token"]
        r = requests.get(
            "https://api.teachfloor.com/v0/courses",
            headers={"Authorization": f"Bearer {access_token}"},
        )

    return r.json()

PHP:

Code
function getCourses(array $installation): array {
    $accessToken = $installation['access_token'];
    $expiresAt   = strtotime($installation['expires_at']);
    if ($expiresAt < time() + 60) {
        $accessToken = refreshToken($installation)['access_token'];
    }

    $ch = curl_init('https://api.teachfloor.com/v0/courses');
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer {$accessToken}"]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code === 401) {
        $accessToken = refreshToken($installation)['access_token'];
        // …retry…
    }

    return json_decode($body, true);
}

Refreshing tokens

Access tokens expire after 1 hour. Refresh tokens are valid for 30 days and rotate on every use — the response contains a fresh refresh_token that supersedes the previous one; store it immediately.

Code
POST https://api.teachfloor.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<the-refresh-token>
&client_id=<the-client-id>
&client_secret=<the-client-secret>

Response:

Code
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGc...(new)...",
  "refresh_token": "def50200...(new)..."
}

Store the new access_token, refresh_token, and the new expiry (now() + expires_in seconds). The old refresh token is invalidated the moment this request succeeds — using it again returns invalid_grant.

Node.js:

Code
async function refreshToken(installation) {
  const body = new URLSearchParams({
    grant_type:    'refresh_token',
    refresh_token: installation.refresh_token,
    client_id:     installation.client_id,
    client_secret: process.env.TEACHFLOOR_CLIENT_SECRET,   // from your app config
  })

  const res = await fetch('https://api.teachfloor.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body,
  })

  if (!res.ok) throw new Error(`refresh failed: ${res.status}`)

  const { access_token, refresh_token, expires_in } = await res.json()
  const expires_at = new Date(Date.now() + expires_in * 1000).toISOString()

  await updateInstallation(installation.organization_id, {
    access_token, refresh_token, expires_at,
  })

  return { access_token, refresh_token, expires_at }
}

Python:

Code
def refresh_token(installation):
    r = requests.post(
        "https://api.teachfloor.com/oauth/token",
        data={
            "grant_type":    "refresh_token",
            "refresh_token": installation["refresh_token"],
            "client_id":     installation["client_id"],
            "client_secret": os.environ["TEACHFLOOR_CLIENT_SECRET"],   # from your app config
        },
    )
    r.raise_for_status()
    body = r.json()
    body["expires_at"] = (
        datetime.now(timezone.utc) + timedelta(seconds=body["expires_in"])
    ).isoformat()
    update_installation(installation["organization_id"], body)
    return body

PHP:

Code
function refreshToken(array $installation): array {
    $ch = curl_init('https://api.teachfloor.com/oauth/token');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
        'grant_type'    => 'refresh_token',
        'refresh_token' => $installation['refresh_token'],
        'client_id'     => $installation['client_id'],
        'client_secret' => getenv('TEACHFLOOR_CLIENT_SECRET'),   // from your app config
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);

    $body['expires_at'] = gmdate('c', time() + $body['expires_in']);
    updateInstallation($installation['organization_id'], $body);
    return $body;
}

Retry pattern: on any 401 from a public API call, refresh once and retry. Don't refresh preemptively on every call — every unnecessary refresh rotates the refresh token, which can race with concurrent workers of your own.

---

Sign in with Teachfloor (OpenID Connect)

If your app declares oauth.authorize in its manifest, users can sign in to your app via Teachfloor — same UX as "Sign in with Google" or "Sign in with GitHub." Adding the openid scope on the authorize request unlocks OpenID Connect: your callback receives an id_token (a signed JWT) identifying the user, in addition to the standard OAuth access + refresh tokens.

The primary use case: users installing your app via Teachfloor's marketplace get dropped onto your setup page already signed in — no re-authentication, no separate account creation.

Discovery

Teachfloor publishes standard OIDC discovery so any conformant OIDC client library (Node openid-client, Python authlib, Go go-oidc, PHP league/oauth2-client, etc.) auto-configures with one URL:

Code
https://app.teachfloor.com/.well-known/openid-configuration

Public keys for id_token signature verification:

Code
https://app.teachfloor.com/.well-known/jwks.json

Both endpoints are cacheable (1h TTL); your OIDC client library handles caching automatically.

The authorize URL

Redirect the user's browser to:

Code
https://app.teachfloor.com/oauth/authorize
  ?client_id=<YOUR_CLIENT_ID>
  &response_type=code
  &scope=openid+profile+email
  &redirect_uri=<YOUR_CALLBACK_URL>
  &state=<CSRF_TOKEN>

Required params:

• client_id — your app's client_id (from teachfloor apps create or the Developer dashboard)
• response_type=code — authorization-code flow
• scope — space-separated list; must include openid for OIDC; add profile/email for additional claims. Any scope not declared in your manifest's permissions returns invalid_scope
• redirect_uri — must match one of the redirect_uris declared in your manifest's oauth.authorize block exactly
• state — CSRF token you generate + verify on the callback

Optional:

• prompt=none — silent auth (see below)
• organization=<slug> — pin the flow to a specific organization when the user is a member of multiple orgs where your app is installed

Handling the callback

Teachfloor redirects the user's browser to your redirect_uri with ?code=<AUTH_CODE>&state=<YOUR_STATE>. Exchange the code for tokens:

Code
// Node example using stock fetch — most OIDC libraries do this for you
const response = await fetch('https://app.teachfloor.com/oauth/token', {
  method:  'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body:    new URLSearchParams({
    grant_type:    'authorization_code',
    code:          authCode,
    client_id:     process.env.TEACHFLOOR_CLIENT_ID,
    client_secret: process.env.TEACHFLOOR_CLIENT_SECRET,
    redirect_uri:  process.env.TEACHFLOOR_REDIRECT_URI,
  }),
})
const tokens = await response.json()
// tokens contains: access_token, refresh_token, expires_in, token_type, scope, id_token

Verifying the id_token

The id_token is a JWT signed with RS256. You MUST verify:

1. Signature — against Teachfloor's public key from the JWKS endpoint
2. iss claim equals https://app.teachfloor.com
3. aud claim equals your client_id
4. exp claim is in the future

Most OIDC client libraries do all four automatically. Example with Node's openid-client:

Code
import { Issuer } from 'openid-client'

// Once at startup
const teachfloor = await Issuer.discover('https://app.teachfloor.com')
const client = new teachfloor.Client({
  client_id:     process.env.TEACHFLOOR_CLIENT_ID,
  client_secret: process.env.TEACHFLOOR_CLIENT_SECRET,
  redirect_uris: [process.env.TEACHFLOOR_REDIRECT_URI],
  response_types: ['code'],
})

// In your callback handler
const params    = client.callbackParams(req)
const tokenSet  = await client.callback(process.env.TEACHFLOOR_REDIRECT_URI, params, { state: savedState })
const claims    = tokenSet.claims()
// claims: { sub, iss, aud, iat, exp, email, email_verified, name }

The sub claim is a stable identifier for the user across sessions — use it as your foreign-key when linking a Teachfloor user to a row in your database. email is convenient but users can change their email address; sub is guaranteed stable.

Silent sign-in (prompt=none)

For zero-UI silent authentication — e.g. after a fresh install, dropping the user onto your setup page already signed in — add &prompt=none to the authorize URL. Behavior per OIDC Core §3.1.2.6:

• User is signed in to Teachfloor + your app is installed for their org → immediate redirect to your callback with ?code=... (no consent screen shown)
• User is NOT signed in → redirect back with ?error=login_required — fall back to your normal sign-in form
• Your app is not installed for any of the user's orgs → redirect back with ?error=interaction_required — direct them to install first
• Requested scopes exceed what's in your manifest → redirect back with ?error=invalid_scope — a real developer bug on your side

Handling errors: any ?error=... on the callback is a normal failure mode, not an exception. Show a helpful message or redirect to a fallback (magic link, "install first" prompt, etc.) — don't crash.

The organization disambiguation param

If a user belongs to multiple organizations that all have your app installed, the consent screen would normally show a picker. When you know which org the flow is for (e.g. post-install redirect from Teachfloor includes ?organization=<slug>), forward that slug in your authorize URL:

Code
https://app.teachfloor.com/oauth/authorize?...&organization=acme

Silent auth pins to that specific org. If the user isn't a member of that org (or the app isn't installed there), you get interaction_required.

Recommended end-to-end pattern for post-install silent sign-in

1. In your manifest, post_install_action.url = https://my-app.com/setup?organization=<slug> (Teachfloor auto-appends the org slug)
2. On landing at your setup page, check if the user has an existing session on your side — if yes, render the setup UI
3. If no session, redirect the user's browser to /oauth/authorize?...&prompt=none&organization=<slug> (forward the org slug from the URL)
4. In your OIDC callback, exchange the code, verify the id_token, mint a session cookie keyed to the user's sub claim, redirect back to your setup page
5. On subsequent renders, the session cookie exists — go straight to the setup UI

Total user-visible latency for the silent auth: ~500ms-1s (comparable to "Sign in with Google" when you're already logged in).

Failure fallback

Users who reach your setup page from a shared link or bookmark (no active Teachfloor session in this browser) will hit error=login_required. Provide a fallback flow — magic link, password login, or a "Sign in with Teachfloor" button that runs the same authorize URL WITHOUT prompt=none (which then shows the interactive consent screen).

Revocation

On uninstall — every access token and refresh token issued for that installation is revoked automatically. The app.uninstalled webhook fires just before revocation; use it to purge the installation from your side:

Code
async function handleAppUninstalled(event) {
  await deleteInstallation(event.data.organization.id)
}

After the uninstall completes, any API call with the old access_token returns 401 and any refresh with the old refresh_token returns invalid_grant. Neither can be recovered — the org would need to reinstall the app to get new tokens.

On version upgrade — the old tokens are revoked and the new version's install fires a fresh app.installed webhook with new tokens. If the new version's permissions changed, the new tokens carry the new scope set. Treat this the same as any other install event.

On manifest re-push of the same version — existing tokens keep working.

Security

• Never log or transmit client_secret, access_token, or refresh_token outside your controlled backend. Redact them from error reports and observability tools.
• Store tokens encrypted at rest. If your database is compromised, plaintext tokens are as good as full account access.
• Verify the webhook signature before trusting the payload. The credentials block only appears in webhooks that pass HMAC-SHA256 signature verification with your app's signing secret — see Signature verification.
• HTTPS only. Every OAuth call is HTTPS-only. Any redirect URL you use for post_install_action.url or oauth.authorize.redirect_uris must be HTTPS (loopback http://localhost allowed for local dev only).
• Scope-limit your tokens. Only declare the permissions your app actually needs. A courses:read token can't reach /v0/members or any other endpoint outside its declared scopes.

For authorize (OIDC) flows specifically:

• Always verify the id_token signature against Teachfloor's JWKS. Never trust an id_token's claims without signature verification — use a standard OIDC client library that enforces this by default.
• Always verify iss, aud, and exp on incoming id_tokens. An attacker who obtained an id_token intended for a DIFFERENT app should not be able to sign in to yours.
• Always validate the state parameter on the callback. Reject callbacks whose state doesn't match what you generated when starting the flow. This is the CSRF defense for the OAuth code flow.
• Never accept access tokens from the browser as evidence of identity. Only the id_token, verified server-side, is trusted identity. Access tokens from the browser can be replayed or stolen.
• Use short-lived session cookies keyed to sub. Don't store the id_token in a cookie or in localStorage — turn it into your app's own session immediately, then discard.

Next Steps

→ Continue to Permissions

Additional Resources

• Webhooks - The delivery mechanism for the credentials block on app.installed.
• Permissions - The manifest permission catalog; OAuth scopes are derived from a subset of it.
• App Manifest - The full manifest schema, including the oauth block.