Docs
Skip to content

Architecture_

Understand how partner platforms connect to Appwrite with OAuth connect, organization API keys, and Console versus project SDKs.

2 min read

Raw

Partner platforms sit above Appwrite organizations and projects. Your backend orchestrates Console-level resources, then uses project-scoped credentials to manage each customer's Appwrite backend.

High-level flow

  1. Your platform authenticates with Appwrite using OAuth tokens (user-linked) or an organization API key (platform-owned).
  2. Console APIs manage organizations, projects, domains, billing context, and org-level settings.
  3. Project APIs manage databases, storage, functions, auth users, and other resources inside each project.
  4. Your product UI exposes a subset of these capabilities to your customers.

OAuth connect architecture

With OAuth connect, a user signs in to Appwrite and grants your OAuth app permission to act on their organizations:

  • Your platform stores refresh tokens securely on the server
  • Console API calls use the user's delegated access
  • Scopes limit which organizations and operations your app can perform
  • Users can revoke access from Appwrite at any time

This model fits products where customers bring their own Appwrite organization or want explicit consent before you manage their infrastructure.

Learn more in OAuth connect.

Org API key architecture

With organization API keys, your platform acts as a trusted backend inside your Appwrite organization:

  • You create projects, domains, and resources for each customer
  • Org API keys authenticate Console API calls with organization-scoped permissions
  • You map customers in your database to Appwrite project IDs
  • Your backend proxies or wraps Appwrite APIs for your product's UI

This model fits multi-tenant platforms that provision isolated Appwrite projects per customer.

Learn more in Org API keys.

Console SDK vs project SDK

SDKEndpoint projectManages
Console (setProject('console'))consoleOrganizations, projects, domains, org settings
Project (setProject('<PROJECT_ID>'))Customer projectDatabases, storage, functions, users, messaging

Partner platforms typically use both: Console SDK for provisioning, project SDK (with a project API key) for day-to-day resource management.

Security considerations

  • Store API keys and OAuth tokens only on your server
  • Use the minimum scopes required for each integration path
  • Rotate organization and project API keys on a schedule
  • Audit Console API usage and map actions to customers in your platform
  • Never pass organization API keys to browser or mobile clients

Related guides

Was this page helpful?

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