Marketplaces_

Build an OAuth app marketplace with the Apps API and OAuth connect. Publish integrations, let organizations install them, and manage grants on your platform.

4 min read

Raw

Use this guide when you run a marketplace where Appwrite organizations discover, install, and manage third-party integrations. Your platform lists OAuth apps, starts authorization on install, and tracks which apps are connected to each customer organization.

Marketplace roles

Role	Responsibility
Marketplace operator (you)	Curates the catalog, registers or approves OAuth apps, runs install and uninstall flows
Integration developer	Builds the app that requests Console scopes after install
Organization admin	Browses your marketplace and approves access to their Appwrite organization

Appwrite separates publishing an OAuth client from consuming OAuth on behalf of a user:

Apps API: create and manage OAuth app records (client_id, redirect URIs, secrets, branding)
OAuth connect: send users through consent and call Console APIs with delegated tokens

Architecture

Typical install flow:

Organization admin clicks Install in your marketplace
Your backend calls oauth2.authorize with the app's clientId and scopes
Admin signs in to Appwrite and approves consent
Appwrite redirects to your callback with an authorization code
Your backend exchanges the code for tokens and saves an installation record
The integration backend calls your API; you use stored tokens for Console API requests on that org

Your marketplace backend owns the catalog and installation state. Integration backends call your API; you proxy Console requests with stored tokens or pass short-lived delegated credentials according to your trust model.

Step 1: Register apps with the Apps API

Each listing in your marketplace maps to an OAuth app. Create apps programmatically when a developer submits an integration, or register them in the Console and import the appId into your catalog.

Save metadata your marketplace UI needs: app.$id, name, logo URIs, requested scopes, and developer contact. See Apps API for update, list, and secret rotation.

Step 2: Build your catalog

Your catalog is application data outside Appwrite. A typical record:

Field	Purpose
`appwriteAppId`	OAuth `client_id` from the Apps API
`name`, `description`, `logoUri`	Marketplace listing (can mirror app fields)
`scopes`	Scopes shown to the admin before install
`category`	Browse and search in your UI
`published`	Whether the listing is visible

Use apps.list and apps.get to sync branding or enabled state from Appwrite when integrations update their app settings.

Step 3: Start install with OAuth

When an organization admin clicks Install, start the authorization code flow with the app's clientId and the scopes that integration requires.

Validate state on callback to bind the authorization to the correct organization in your platform. Request only the scopes from OAuth connect scopes that the integration needs.

Step 4: Exchange tokens and record the install

On your callback route, exchange the authorization code for access and refresh tokens using the app's client secret. Persist an installation row keyed by your tenant or organization ID and appwriteAppId.

Refresh access tokens before they expire. When an admin uninstalls, revoke the grant in Appwrite and delete stored tokens.

Step 5: Let integrations act on installed orgs

After install, the integration backend calls your marketplace API with an install ID or org ID. Your backend uses the stored token to call Console APIs:

Alternatively, pass a short-lived token or scoped proxy credential to the integration if you do not want third-party servers to hold long-lived refresh tokens. See Proxy for wrapping Console APIs behind your platform.

Developer onboarding

If third parties publish into your marketplace:

Developer registers with your platform
You review scopes and redirect URIs
You create the OAuth app with the Apps API (or approve a Console-registered app)
You publish the listing after testing the install flow in a staging organization

Keep redirect URIs under domains you control (marketplace.example.com/oauth/callback) so token exchange stays on your backend.

Uninstall and revocation

When an admin removes an integration:

Delete or disable the installation record in your database
Revoke refresh tokens and grants in Appwrite
Notify the integration developer if you operate webhooks for install lifecycle events

Treat uninstall as a security event: integrations must stop calling Console APIs immediately.

Security checklist

Register redirect URIs that match your callback exactly
Store client secrets and refresh tokens encrypted at rest
Show requested scopes in your UI before redirecting to consent
Rotate secrets with createSecret and deleteSecret on the Apps API
Audit installs per organization and alert on scope changes

Apps API

Create and manage OAuth app records.

OAuth connect setup

Authorization code flow and token exchange.

OAuth scopes

Request the minimum Console scopes per integration.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.