Frontdesk

A support desk for the people who use your customers' apps, built on Appwrite OAuth connect.

A customer connects their Appwrite account, picks the projects Frontdesk may work in, and your support team gets one screen for their end users: search accounts, see the devices they are signed in on, verify an email, sign a session out, block an account. Nobody needs an Appwrite Console seat, and the customer never sends you an API key.

This is the sample app for the Appwrite guide Manage a customer's Appwrite project.

What it shows

• The authorization code flow against /v1/oauth2/console/authorize and /v1/oauth2/console/token
• Reading the grant back: who approved it, which projects it covers, which scopes it carries
• Calling a customer's project with the access token as a bearer token
• Refresh token rotation, and what to do when a customer revokes
• An audit trail of your own, because Appwrite only sees one grant
• Metering with the usage gauges, so the invoice follows the accounts you support

Stack

TanStack Start, React, Tailwind, and node-appwrite. Tokens live in a JSON file under .data/ so the sample runs with no database; a real deployment puts them in a secrets manager.

Setup

1. In the Appwrite Console, open your organization, go to Marketplace, and create an app.

2. On the app's OAuth client page, keep the client type Confidential and add http://localhost:7700/oauth/callback as a redirect URI. Copy the client ID.

3. On OAuth secrets, create a secret and copy it.

4. Copy the environment file and fill it in:

   cp .env.example .env

   APPWRITE_ENDPOINT=https://fra.cloud.appwrite.io/v1
   APPWRITE_CLIENT_ID=
   APPWRITE_CLIENT_SECRET=
   APP_URL=http://localhost:7700

5. Install and run:

   pnpm install
   pnpm dev

Open http://localhost:7700 and select Connect Appwrite account.

Demo data

To fill a throwaway project with believable support cases, create a project API key with the users and teams scopes and run:

SEED_ENDPOINT=https://fra.cloud.appwrite.io/v1 \
SEED_PROJECT=<PROJECT_ID> \
SEED_KEY=<API_KEY> \
node scripts/seed-demo-users.mjs

Pass SEED_RESET=1 to delete the existing users and teams first. Only point this at a project you are happy to empty.

Scopes

Frontdesk requests exactly what its screens use:

Scope	Used for
openid, profile, email	Who approved the connection
project:project.read	The project name shown in the desk
project:users.read, project:users.write	The customer directory and the support actions
project:sessions.read, project:sessions.write	Signed-in devices, and signing them out
project:teams.read	Team memberships on a customer record
project:usage.read	Account counts per project, used for billing

Anything outside that list is refused by Appwrite, not by application code.

Layout

src/lib/appwrite.server.ts   OAuth endpoints and the granted-project lookup
src/lib/session.server.ts    Cookies, token refresh, per-project SDK clients
src/lib/store.server.ts      Connection and audit storage
src/lib/api.ts               Server functions the UI calls
src/routes/oauth.*.tsx       The authorization redirect and the callback
src/routes/desk/*            Projects, customers, activity, connection