Add Sign in with Appwrite docs under Partners #3116
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| <script lang="ts"> | ||
| import Docs from '$lib/layouts/Docs.svelte'; | ||
| import Sidebar, { type NavParent, type NavTree } from '$lib/layouts/Sidebar.svelte'; | ||
|
|
||
| const parent: NavParent = { | ||
| href: '/docs', | ||
| label: 'Apps' | ||
| }; | ||
|
|
||
| const navigation: NavTree = [ | ||
| { | ||
| label: 'Getting started', | ||
| items: [ | ||
| { | ||
| label: 'Overview', | ||
| href: '/docs/partners/apps' | ||
| }, | ||
| { | ||
| label: 'Quick start', | ||
| href: '/docs/partners/apps/quick-start' | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| label: 'Concepts', | ||
| items: [ | ||
| { | ||
| label: 'Registration', | ||
| href: '/docs/partners/apps/registration' | ||
| }, | ||
| { | ||
| label: 'Scopes', | ||
| href: '/docs/partners/apps/scopes' | ||
| }, | ||
| { | ||
| label: 'Consent', | ||
| href: '/docs/partners/apps/consent' | ||
| }, | ||
| { | ||
| label: 'Tokens', | ||
| href: '/docs/partners/apps/tokens' | ||
| }, | ||
| { | ||
| label: 'Device flow', | ||
| href: '/docs/partners/apps/device-flow' | ||
| } | ||
| ] | ||
| } | ||
| ]; | ||
| </script> | ||
|
|
||
| <Docs variant="two-side-navs"> | ||
| <Sidebar {navigation} {parent} /> | ||
| <slot /> | ||
| </Docs> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| --- | ||
| layout: article | ||
| title: Sign in with Appwrite | ||
| description: Build apps that access your users' Appwrite projects and organizations with consent-based, scoped OAuth2 tokens instead of pasted API keys. | ||
| back: /docs | ||
| --- | ||
|
|
||
| Appwrite is an **OAuth 2.1 and OpenID Connect provider**. Your app can send any Appwrite user to a consent screen, ask for access to the projects and organizations they choose, and receive tokens that call their project APIs directly. This is **Sign in with Appwrite**: the same consent flow users know from "Sign in with Google", pointed at their Appwrite account and backend. | ||
|
|
||
| Before this, a tool that worked with a user's Appwrite project asked them to create an API key and paste it in. The key carried whatever scopes and expiry the user picked at creation, worked for one project only, and lived outside their control once pasted. With Sign in with Appwrite, the user approves once, picks the projects your app can reach, and can revoke everything from their account page at any time. | ||
|
|
||
| {% info title="Building your own provider?" %} | ||
| This section is for apps that build on top of Appwrite itself. To make your own product an OAuth2 provider so that third parties can offer "Sign in with your product", see the [OAuth2 server](/docs/products/auth/oauth-server) documentation. | ||
|
Contributor
There was a problem hiding this comment.
This callout still links to Knowledge Base Used: Docs section routing and layout Prompt To Fix With AIThis is a comment left during a code review.
Path: src/routes/docs/partners/apps/+page.markdoc
Line: 13
Comment:
**Provider Link 404s**
This callout still links to `/docs/products/auth/oauth-server`, but that route is not present in the tree. A reader looking for provider-side OAuth docs from this new overview page lands on a 404 unless a separate docs change deploys first. Please point this to a route that ships here, or keep the link out until the target page exists.
**Knowledge Base Used:** [Docs section routing and layout](https://app.greptile.com/appwrite/-/custom-context/knowledge-base/appwrite/website/-/docs/docs-section.md)
How can I resolve this? If you propose a fix, please make it concise. |
||
| {% /info %} | ||
|
|
||
| # What you can build {% #what-you-can-build %} | ||
|
|
||
| Your app authenticates the user once and then acts on their Appwrite resources with the scopes they granted. | ||
|
|
||
| - **Dashboards and monitors** that read usage, logs, and data across the projects a user selects. | ||
| - **Deployment tools** that push functions and sites into a customer's project without holding a key. | ||
| - **CLIs and devices** that sign in with a short user code instead of a browser redirect. | ||
| - **AI agents and MCP clients** that operate under scopes the user can narrow to read-only. | ||
|
|
||
| # How it works {% #how-it-works %} | ||
|
|
||
| {% only_dark %} | ||
|  | ||
| {% /only_dark %} | ||
| {% only_light %} | ||
|  | ||
| {% /only_light %} | ||
|
|
||
| Sign in with Appwrite is the authorization code flow from OAuth 2.1, served by Appwrite. | ||
|
|
||
| 1. **Your app redirects the user** to the Appwrite authorization endpoint with the scopes it needs. | ||
| 2. **Appwrite shows the consent screen.** The user sees your app's name and logo, reviews the requested permissions, and picks which projects and organizations they apply to. They can grant fewer projects than you asked for, or decline entirely. | ||
| 3. **Your app receives an authorization code** at its redirect URI and exchanges it for an access token, a refresh token, and an ID token. | ||
| 4. **Your app calls Appwrite APIs** with the access token as a bearer token, on any of the granted projects, in any region. | ||
|
|
||
| Because the provider is spec-compliant, any OAuth2 or OIDC library works against the discovery document without Appwrite-specific code: | ||
|
|
||
| ```text | ||
| https://cloud.appwrite.io/v1/oauth2/console/.well-known/openid-configuration | ||
| ``` | ||
|
|
||
| Users stay in control after the redirect too. Every authorization appears on their account's applications page, where they see the scopes your app holds and the tokens issued under it, and can revoke a token family or the whole authorization at any time. | ||
|
|
||
| # Explore {% #explore %} | ||
|
|
||
| {% cards %} | ||
| {% cards_item href="/docs/partners/apps/quick-start" title="Quick start" %} | ||
| Register an app and run the full flow, from consent to your first authorized API call. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/registration" title="Registration" %} | ||
| Register your app in the Console and shape its consent screen listing. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/scopes" title="Scopes" %} | ||
| The scope catalog and how grants target specific projects and organizations. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/consent" title="Consent" %} | ||
| What users see, what they can change, and what your app receives. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/tokens" title="Tokens" %} | ||
| Use, refresh, and revoke the tokens Appwrite issues to your app. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/dashboards" title="Dashboards" %} | ||
| Build a read-only dashboard over the projects a user selects. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/deployments" title="Deployments" %} | ||
| Deploy functions and sites into a user's project with write scopes. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/device-flow" title="Device flow" %} | ||
| Sign in from CLIs and devices with a short user code. | ||
| {% /cards_item %} | ||
| {% cards_item href="/docs/partners/apps/agents" title="Agents" %} | ||
|
Comment on lines
+67
to
+76
Contributor
There was a problem hiding this comment.
The Knowledge Base Used: Docs section routing and layout Prompt To Fix With AIThis is a comment left during a code review.
Path: src/routes/docs/partners/apps/+page.markdoc
Line: 67-76
Comment:
**Forward Cards Still 404**
The `device-flow` card now has a route, but the `dashboards`, `deployments`, and `agents` cards still point to pages that are not present under `src/routes/docs/partners/apps`. A reader who clicks any of these Explore cards from the new landing page reaches a docs 404. Please add those pages with this PR or remove these cards until the routes exist.
**Knowledge Base Used:** [Docs section routing and layout](https://app.greptile.com/appwrite/-/custom-context/knowledge-base/appwrite/website/-/docs/docs-section.md)
How can I resolve this? If you propose a fix, please make it concise. |
||
| Connect AI agents and MCP clients to your users' projects. | ||
|
Comment on lines
+67
to
+77
Contributor
There was a problem hiding this comment.
When this Overview page is deployed before the follow-up pages, the Dashboards, Deployments, Device flow, and Agents cards send readers to routes that are not in this change. Those prominent links become 404s from the new docs landing page. Knowledge Base Used: Prompt To Fix With AIThis is a comment left during a code review.
Path: src/routes/docs/partners/apps/+page.markdoc
Line: 60-70
Comment:
**Forward Cards Hit Missing Routes**
When this Overview page is deployed before the follow-up pages, the Dashboards, Deployments, Device flow, and Agents cards send readers to routes that are not in this change. Those prominent links become 404s from the new docs landing page.
**Knowledge Base Used:**
- [Docs section routing and layout](https://app.greptile.com/appwrite/-/custom-context/knowledge-base/appwrite/website/-/docs/docs-section.md)
- [Markdoc content pipeline](https://app.greptile.com/appwrite/-/custom-context/knowledge-base/appwrite/website/-/docs/markdoc-content-pipeline.md)
How can I resolve this? If you propose a fix, please make it concise. |
||
| {% /cards_item %} | ||
| {% /cards %} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| --- | ||
| layout: article | ||
| title: Consent | ||
| description: What users see on the Sign in with Appwrite consent screen, what they can change, and what your app receives. | ||
| back: /docs/partners/apps | ||
| --- | ||
|
|
||
| {% only_dark %} | ||
|  | ||
| {% /only_dark %} | ||
| {% only_light %} | ||
|  | ||
| {% /only_light %} | ||
|
|
||
| Consent is where the user decides. Appwrite hosts the screen, renders what your app asked for, and gives the user the final say over scopes and targets. Your app never sees the screen; it sees the outcome. | ||
|
|
||
| # The consent screen {% #consent-screen %} | ||
|
|
||
| {% only_dark %} | ||
|  | ||
| {% /only_dark %} | ||
| {% only_light %} | ||
|  | ||
| {% /only_light %} | ||
|
|
||
| The screen is built from your [registration](/docs/partners/apps/registration) and your request: | ||
|
|
||
| - **Your app's identity**: the name, logo, and tagline you registered. | ||
| - **Permissions**: each requested scope as a plain-language line, under a one-line summary of the overall reach. | ||
| - **Project access**: a picker for the projects or organizations the grant covers when the request carries project or organization scopes. | ||
|
|
||
| The user signs in first if no session exists, and can switch accounts from the screen itself. | ||
|
|
||
| # Users can grant less {% #partial-grants %} | ||
|
|
||
| What you request is not always what you get. On the consent screen, the user can: | ||
|
|
||
| - Deselect projects or organizations, shrinking where the grant applies. | ||
| - Decline the whole request. | ||
|
|
||
| The permission list itself is not editable. Scopes are granted as you requested them or not at all, which is another reason to request the smallest set that serves your app. | ||
|
|
||
| The token response tells you what you got: `scope` holds the granted scopes, `authorization_details` the granted projects. Build for this from the start. A dashboard that asked for five projects but got two should show two projects, not an error. | ||
|
|
||
| # When the screen is skipped {% #consent-reuse %} | ||
|
|
||
| Appwrite remembers approvals. When a returning user's request asks for nothing new, they skip the screen and land straight back in your app. When anything differs from the stored approval, the screen reappears. Send the same authorization parameters on every sign-in and returning users sign in silently. | ||
|
|
||
| Two `prompt` values override this: | ||
|
|
||
| - `prompt=consent` always shows the screen, even when an approval exists. | ||
| - `prompt=none` never shows it, returning `error=consent_required` or `error=login_required` instead. Use it to check for existing access silently. | ||
|
|
||
| # Revocation {% #revocation %} | ||
|
|
||
| {% only_dark %} | ||
|  | ||
| {% /only_dark %} | ||
| {% only_light %} | ||
|  | ||
| {% /only_light %} | ||
|
|
||
| Every approval appears on the user's account applications page. From there, the user revokes a single token or the whole app, which kills every token your app holds for them. | ||
|
|
||
| Your app gets no notification. Calls and refreshes start returning `401`, and the fix is to send the user through authorization again. | ||
|
|
||
| Revocation goes both ways: when a user disconnects your app on your side, revoke the tokens you hold at the [revocation endpoint](/docs/partners/apps/tokens#revocation). |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.