Introducing a new way to review your PRs.

Read the announcement

appwrite / appwrite

The open-source cloud for agents & devs. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime, WAF and more

View on GitHub

59 documents · Updated Nov 20, 2026

docs / console-authentication-and-project-experience

Console authentication and project experience

The Console is the web workspace for account access, organization and project choice, service setup, API exploration, and project operations. It keeps those flows in one selected project context while applying profile, plan, billing, and organization access rules. This page complements the Console application overview and relates to the video processing API.

Authentication flow

Authentication creates and checks the Console account session before protected organization or project views render. It supports normal sign-in, MFA, email verification, Magic URL sign-in, OAuth relays, and other flows that may need to return to a prior Console location.

Session guard and destinations

RequireAuth is the shared session guard for protected views. It waits for the account check, sends a guest to sign-in, sends an account that needs MFA or email verification to the matching step, and shows a blocked-account screen when access is forbidden. Some routes stay open without a normal Console session, such as OAuth consent, transfer links, alert unsubscribe links, initialization, education entry points, debug demos, and the public player.

After authentication, the Console accepts only safe relative Console paths. External, root, auth, marketing, and malformed destinations are rejected. Optional-auth flows keep their own return context instead of creating a personal organization or project as a side effect.

The normal path is structured as follows:

flowchart TD
    A[Sign in or sign up] --> B{Extra check needed?}
    B -->|MFA| C[MFA verification]
    B -->|Email verification| D[Email verification]
    B -->|No| E[Refresh Console account]
    C --> E
    D --> E
    E --> F{Safe Console destination?}
    F -->|Yes| G[Open requested flow]
    F -->|No| H[Open default organization]

Email verification preserves the requested destination and can complete from a link without an active session. The page limits resends per browser tab and checks the refreshed account after an invalid or spent token, so a successful verification is not shown as a failure after a duplicate submit or link scan.

References: apps/…/RequireAuth.tsx• L34-89 apps/…/RequireAuth.tsx• L139-207 apps/…/RequireAuth.tsx• L328-418 apps/…/post-auth-navigation.ts• L38-110 apps/…/verify-email.tsx• L129-319

Magic URL sign-in

Magic URL sign-in turns a one-time link into a Console session and then opens its checked destination. If a different real account is active, the Console asks before replacing it and signs out the old account before retrying the link. Missing, invalid, or expired links show an error, while an anonymous project session can be replaced without the same prompt.

References: apps/…/auth.magic-url.tsx• L21-127 apps/…/MagicUrlLoginCard.tsx• L15-111

Organization and project selection

An organization groups projects and provides their access, plan, billing, domain, and ownership context. The Console lets a user choose an organization, find or create a project, switch project context, and enter an environment without losing the surrounding account or organization state.

Organization overview

The organization overview is the entry point for project work. Its tabs and actions follow the active Console profile and the user's organization access. Project lists support search, paging, grid or list display, pinned projects, project-level access scope, and quick access to project activity.

The same view also carries organization-level work. Members, settings, billing, compliance, domains, marketplace content, and organization applications appear only when the profile and role allow them. Project creation can include a region and plan effects, then opens the new project after success. A first-project path uses focused onboarding while ending in the same project workspace.

References: apps/…/View.tsx• L402-445 apps/…/View.tsx• L620-745 apps/…/View.tsx• L908-930 apps/…/View.tsx• L1323-1391

Organization and project switcher

The project switcher is the main cross-project control inside a project workspace. It can show organization choice when the account can move between organizations, search projects, load more projects, preserve pinned projects, show plan or billing warnings, and open project or organization creation flows.

Organization selection is part of project selection. The Console prepares the selected organization's project list and access scope before it changes the visible list. This keeps the switcher from showing stale projects during an organization change.

References: apps/…/ProjectSelector.tsx• L270-317 apps/…/ProjectSelector.tsx• L399-568 apps/…/ProjectSelector.tsx• L652-718 apps/…/ProjectSelector.tsx• L1234-1465

Project environments

An environment is a separate working context linked to a parent project. The parent project represents production, while each environment has its own resources and can use the same project workspace. The Console labels production clearly and keeps rename and delete actions on non-production environments.

Environment creation can start empty or copy selected project structure. The user can enter the new environment while the copy continues in the background. The switcher also supports saved ordering, plan upgrade guidance, and a return to production. Environment support is profile-controlled and Cloud-only.

References: apps/…/EnvironmentSwitcher.tsx• L270-351 apps/…/EnvironmentSwitcher.tsx• L377-445 apps/…/EnvironmentSwitcher.tsx• L514-645

Project access and transfer

The project entry flow resolves project access, billing state, plan use, blocked state, and pause state before it opens normal service views. A blocked, paused, unpaid, or plan-limited project can show a focused status curtain. A missing or forbidden project shows an access error without a misleading project shell.

Project transfer moves ownership between organizations through a direct move or a time-limited claim link. The transfer checks membership, billing, and project limits before it completes. The organization transfer API describes the service contract behind this flow.

References: apps/…/projects.$projectId.tsx• L214-377 apps/…/projects.$projectId.tsx• L830-945 apps/…/View.tsx• L55-136

Project workspace

The project workspace is the shared frame for product work. It groups connection, build, deployment, data, observation, review, security, and media tasks around the selected project or environment.

The shell keeps plan limits, billing warnings, paused or blocked state, environment identity, and long-running work near the active service. Navigation and create actions follow profile features and organization access. A surface can therefore be visible, disabled, or redirected without changing the project context.

Project overview

The overview connects project identity and endpoint details with applications, API keys, service resources, quick starts, and usage charts. Resource cards distinguish an empty service from a failed read and give a direct first action when a service has not been used.

Usage panels can show bandwidth, requests, storage, executions, and compute. They use plan-aware date ranges and intervals, keep a prior view while a new range loads, and expose resource breakdowns where the plan supports them. The overview also links connection work to registered applications and API keys.

References: apps/…/Overview.tsx• L141-211 apps/…/Overview.tsx• L596-741 apps/…/Overview.tsx• L890-1049 apps/…/Overview.tsx• L1352-1391 apps/…/OverviewListCard.tsx• L68-169 apps/…/OverviewListCard.tsx• L296-435

Application connection and onboarding

The connection experience registers an application against the current project and gives a developer setup information for web, mobile, or desktop targets. A client ping helps confirm that the registered application reaches the project.

The Apps view supports platform identity, updates, deletion, search, and a warning for wildcard web hostnames. Onboarding turns first setup into a progress view. Production shows a project checklist, while an environment shows a focused connection step.

References: apps/…/View.tsx• L44-116 apps/…/PlatformDrawer.tsx• L43-176 apps/…/WildcardWarning.tsx• L9-31 apps/…/View.tsx• L675-949

Service configuration

Service pages turn project resources into focused management surfaces. They normally combine route tabs, search, filters, paging, resource creation, plan limits, and access-aware actions. Project settings use the same model for project identity, protocols, services, domains, variables, webhooks, migrations, SMTP, integrations, and destructive project actions.

Custom domains share an ownership and DNS verification model across API, Functions, and Sites. A domain can need organization registration, ownership proof, DNS checks, and a later certificate check. Pending views keep the domain visible and expose the next action, logs, or retry path. Function domains can also target an active deployment, a Git branch, a redirect, or a Cloud-only inbound email service.

Git connections link Functions or Sites to a provider installation and repository. The Console keeps a connection visible even when provider details cannot be read, so the user can reconnect or remove a broken link instead of seeing a false empty state.

References: apps/…/Domains.tsx• L65-177 apps/…/AddDomainWizard.tsx• L43-193 apps/…/VerifyDomainContent.tsx• L816-1217 apps/…/UpdateDomain.tsx• L35-108 apps/…/Domains.tsx• L68-138 apps/…/AddDomainWizard.tsx• L52-243 apps/…/GitSettingsCard.tsx• L58-83 apps/…/CreateSiteView.tsx• L107-151

Authentication overview and security actions

Project Auth settings control how end users enter a project and what an operator can do during a security event. The Auth workspace covers an overview, users, teams, policies, OAuth providers, the OAuth2 server, email templates, and settings.

Users and teams use URL-backed search, filters, sorting, paging, list or grid views, and access-aware create actions. Security settings and policy surfaces are role-gated. Email templates support verification, Magic URL, OTP, recovery, invitation, MFA, and session-alert messages across locales. Custom SMTP is required before a user can edit message content.

References: apps/…/View.tsx• L134-321 apps/…/View.tsx• L1121-1214 apps/…/View.tsx• L1325-1495 apps/…/Templates.tsx• L77-167 apps/…/Templates.tsx• L169-245 apps/…/Templates.tsx• L536-920

Storage and database workspaces

Storage settings control bucket identity and the rules applied to new files. Database views combine schema design, indexes, relationships, permissions, and row or document work. Backup views add scheduled and manual archives plus restore actions for eligible projects.

The workspace keeps plan limits and environment scope visible because those rules change which storage, database, and backup actions are possible. A restore remains visible as migration work until its final state.

References: apps/…/BucketSettings.tsx• L48-137 apps/…/View.tsx• L91-121 apps/…/Backups.tsx• L138-257 apps/…/Backups.tsx• L415-495

Firewall rules and traffic protection

Firewall views join traffic observation with protection rules for the project API, a Function, or a Site. Rules can deny, rate limit, challenge, or redirect matching requests. Attack mode gives a fast challenge switch for supported scopes.

The rule flow previews the effect of conditions before save and keeps schedule time zones explicit. Usage and analytics values can open a prefilled firewall rule when the source resource and permissions allow it.

References: apps/…/Firewall.tsx• L32-155 apps/…/TrafficOverview.tsx• L270-351 apps/…/Rules.tsx• L101-177 apps/…/View.tsx• L92-170

Function and Site experiences

Functions and Sites connect project resources to deployed code. Their overviews keep the active deployment, recent history, domains, usage, and protection state near the resource so an operator can move from a status to its next action.

Function creation can use a template, runtime settings, variables, compute, a domain, and an optional Git connection. Site creation can use a template, repository, repository URL, or manual archive, then collects framework, build, variables, domain, and optional analytics settings. A site can add analytics for production domains only. The setting keeps existing analytics data when disabled and explains the content-security policy sources required for tracking.

Deployment views retain build state, logs, previews, screenshots, domains, and recovery actions. Partial creation routes to the resource that already exists instead of inviting a duplicate attempt.

References: apps/…/Overview.tsx• L28-133 apps/…/TemplateConfigView.tsx• L235-391 apps/…/Overview.tsx• L51-176 apps/…/CreateSiteView.tsx• L360-625 apps/…/AnalyticsToggle.tsx• L5-37 apps/…/AnalyticsCard.tsx• L22-141

Video workspace

The Videos workspace manages source videos and their playback outputs inside the project context. A video detail view groups overview, renditions, captions, timeline, streaming, player installation, and settings under one resource identity.

The list and profile views support search, filters, sorting, paging where needed, empty states, bulk actions, and access-aware creation. Renditions show encoding status and can be retried or removed. Streaming and Install explain which playback outputs are ready and generate player setup code. The video processing API describes the service contract behind these views.

Captions are now the user-facing name for subtitle tracks. Users can upload or create a caption, edit cues against video playback, import or export caption files, set language and default-track details, validate timing, and save a new packaged track. The editor protects unsaved work when the user leaves. Caption detail uses the current track file and offers a path to start with an empty track when the source cannot be read.

References: apps/…/View.tsx• L77-124 apps/…/View.tsx• L333-523 apps/…/Layout.tsx• L78-172 apps/…/Layout.tsx• L222-351 apps/…/View.tsx• L29-75 apps/…/View.tsx• L41-193 apps/…/View.tsx• L26-130 apps/…/SubtitleEditor.tsx• L160-211 apps/…/SubtitleEditor.tsx• L517-627 apps/…/video-tabs.ts• L14-101

API exploration

The Playground is an interactive way to learn and test APIs for the current project. It combines REST request exploration with a Realtime debugger and keeps useful REST state in the project URL.

REST request exploration

REST mode uses the API specification to present services, operations, inputs, authentication needs, and responses. A selected service and operation can be opened from a shared Playground URL.

Authentication follows the selected operation. Client requests can use guest or project-user context. Server requests can use a project API key or session access when supported. The UI shows required scopes when a key cannot cover an operation, while manually entered credentials remain in the browser for reuse.

References: apps/…/View.tsx• L23-73 apps/…/Rest.tsx• L7-53 apps/…/projects.$projectId.tsx• L449-508 apps/…/auth.ts• L29-84

Realtime debugging

Realtime mode opens a WebSocket session for the current project and lets a user act as a guest or project user. The user can build subscriptions, connect or disconnect them, add sample messages, filter the log, and inspect payloads and connection state.

REST URL state remains separate from Realtime state. A REST deep link selects REST even when the saved mode is Realtime, and returning to REST restores the last operation. Realtime configuration can persist after live connections close.

References: apps/…/Realtime.tsx• L359-445 apps/…/Realtime.tsx• L565-681 apps/…/View.tsx• L41-73

Analytics experience

Analytics lets a project collect and study events from web, mobile, and agent sources. A property defines the source and tracking settings. The Console guides setup, confirms the first event, and then provides trends, dimensions, filters, live visitors, and exports.

Analytics property setup

Property creation asks for a name, type, domain when relevant, and an SDK or REST platform. The setup view provides install code and can prepare a prompt for an AI coding tool. A live status card waits for the first event so the user can confirm that tracking reaches Appwrite before opening the dashboard.

Web tracking can use direct delivery or a proxy mode. Property settings control the name, type, enabled state, user identification, domain, allowed origins, and proxy guidance.

References: apps/…/View.tsx• L71-145 apps/…/InstallTrackingDialog.tsx• L122-179 apps/…/PropertySettings.tsx• L46-117

Analytics dashboard and filters

The dashboard combines a date range, comparison period, interval, filters, totals, change values, time series, and type-specific dimensions. Missing time buckets remain visible so the selected window does not look shorter when no events were recorded in part of it.

Filters are shared across overview cards, breakdowns, event views, and exports. Their sanitized state stays in the URL so a report can be shared and restored. The export menu uses the same range and filters to produce a data package or PDF report. Recent activity is checked separately from the selected report range, and live visitor polling runs only while the page is visible.

References: apps/…/View.tsx• L161-200 apps/…/View.tsx• L451-485 apps/…/AnalyticsOverview.tsx• L381-445 apps/…/AnalyticsFilterChips.tsx• L11-40 apps/…/ExportMenu.tsx• L48-115 apps/…/LiveVisitors.tsx• L56-81

Operational views

Operational views help a user understand project health and activity after setup. They connect usage, monitors, alerts, audit events, code reviews, deployments, domains, video processing, and migrations to the project or resource that produced them.

Usage and activity

Usage is organized by metric category with date ranges, chart intervals, filters, retention limits, and monitoring links. The navigation covers traffic, compute, databases, Storage, Auth, Realtime, Messaging, webhooks, avatars, Functions, and Sites. Usage filters can also become a firewall rule when the project and user have the required scope.

Activity provides an audit view with resource identity, actor and client context, SDK source, retention-aware dates, paging, URL-backed filters, and deep-linked event details.

References: apps/…/Layout.tsx• L409-511 apps/…/Layout.tsx• L513-616 apps/…/Layout.tsx• L754-959 apps/…/View.tsx• L658-775 apps/…/View.tsx• L1111-1204

Monitors and alerts

Monitors turn a usage metric and threshold into a project or resource rule. A monitor can be firing, pending, okay, or paused and can notify selected organization roles. Its detail view combines the latest value, history, condition, recipients, severity, and actions.

Alerts record monitor firings. The Alerts view groups history by day, filters firing and resolved states, loads more records, and shows acknowledgement, notifications, peak value, and recovery. Monitor creation can be prefilled from a usage category, resource breakdown, or a URL link, then consumes the query so a refresh does not reopen the form.

References: apps/…/Layout.tsx• L11-75 apps/…/projects.$projectId.monitors.tsx• L10-33 apps/…/projects.$projectId.monitors.index.tsx• L41-139 apps/…/projects.$projectId.monitors.alerts.tsx• L21-71 apps/…/Layout.tsx• L897-924

Code review

Code review connects GitHub repositories to a project and reviews pull requests as they change. The Review area separates review history, repository enrollment, learned guidance, and performance.

Past reviews remain after repository removal. Review history shows status, verdict, merge confidence, trigger, findings, and trace data. Performance adds date and repository views for author approval, findings, fix rates, useful findings, confidence, and finding categories. Repository changes stay subject to organization permission and the Console and review-service gates. The code review API describes the service contract behind this view.

References: apps/…/View.tsx• L25-108 apps/…/View.tsx• L117-221 apps/…/Performance.tsx• L197-238 apps/…/Performance.tsx• L302-519

Service activity and deployments

Service views extend the operational picture with deployment, execution, domain, database, message, and video records. Functions and Sites expose deployment state and recovery actions. Domains expose verification history and logs. Videos expose encoding progress, captions, playback readiness, streaming URLs, and player setup.

These views keep the active resource and its history in the same project context. A user can move from a failed or pending state to the next action without losing resource identity or returning to a general list.

References: apps/…/Deployments.tsx• L245-405 apps/…/SiteDeployments.tsx• L241-386 apps/…/ViewLogs.tsx• L20-78 apps/…/View.tsx• L46-160 apps/…/View.tsx• L51-180

Migration progress

Migration progress keeps long-running CSV export, CSV import, environment copy, database restore, and related work visible during the current Console session. Realtime events and migration records add active work to the matching project, while progress states distinguish waiting, active, successful, failed, skipped, and warning items.

The session scope is deliberate. Reloading the Console does not turn old migration records into active progress alerts, while work that becomes active during the session can appear without a page reload. Pending and processing items remain unfinished until the resource reports a final state.

References: apps/…/SessionMigrationsContext.tsx• L1-5 apps/…/SessionMigrationsContext.tsx• L18-48 apps/…/SessionMigrationsContext.tsx• L163-211

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep sign-in, MFA, email verification, Magic URL account switching, optional-auth routes, safe return paths, and default organization selection aligned.
  • Keep organization access checks aligned across tabs, project creation, billing, domains, members, pins, project scopes, and project switching.
  • Keep project and environment scope aligned across the switcher, project shell, environment banner, backups, database workspaces, videos, and migration progress.
  • Keep overview cards aligned with service navigation, API keys, registered apps, usage tabs, quick starts, plan limits, profile gates, and project permissions.
  • Keep Auth tabs, user and team URL state, security policies, OAuth2 server visibility, templates, SMTP prerequisites, and access checks aligned.
  • Keep domain ownership, organization domain links, DNS alternatives, certificate state, logs, retry actions, and service-specific targets aligned across API, Functions, and Sites.
  • Keep Git installation state distinct from repository lookup state so a broken provider connection remains visible and recoverable.
  • Keep video tab names, caption routes, rendition readiness, streaming URLs, player setup, subtitle file storage, unsaved editor state, and API contracts aligned.
  • Keep monitor routes, alert links, prefilled metric queries, plan limits, acknowledgements, and notification delivery aligned after the monitor move.
  • Keep analytics property types aligned with install guidance, first-event checks, site analytics toggles, filter URL state, live visitors, and exports.
  • Keep review repository enrollment separate from review history and performance data. Preserve running-review refresh and permission gates.

Important failure modes

TriggerConsequenceGuard
An unverified or blocked account enters a protected project routeOrganization or project work fails or the Console shows a misleading shellApply the shared session guard and profile-controlled verification before rendering project work
A verification link is submitted twice or consumed by a scannerA successful verification appears to failRefresh the account after an invalid token and trust its verified state
An OAuth, device, education, or transfer flow creates a default organizationThe external flow returns to the wrong contextPreserve optional-auth destinations and transfer organization choice
A project or environment ID is used without its parent scopeThe user sees the wrong resources or controlsResolve organization and parent-project scope before loading child data
A project is paused, blocked, unpaid, or plan-locked after the shell startsService actions look usable although the project cannot operateResolve project and organization state before child views and show the matching status curtain
An organization switch reuses the prior organization's project listA user can select a project from the wrong organizationLoad the target organization's prefs, scope, pinned projects, and list before switching
A wildcard app hostname reaches productionAny website can send requests to the projectWarn about wildcard hosts and require a real application domain
A domain is treated as verified before DNS or the certificate is readyTraffic fails or the user cannot see the next required DNS actionKeep DNS checks, certificate state, logs, and retry actions visible together
A broken Git installation is treated as an empty repository listThe user disconnects the wrong resource or creates a duplicate connectionKeep the stored connection visible and offer provider reconnect or disconnect actions
A caption editor leaves with unsaved cuesTrack metadata or cue changes are lostBlock navigation and require an explicit discard decision
A video playback tab opens before a rendition is readyStreaming URLs and player setup appear unusableKeep playback disabled until a ready rendition exists
A restore, environment copy, or rendition job is shown as complete too earlyThe target resource appears ready before its work finishesTie visible state and actions to migration or encoding progress
A monitor link retains a consumed prefill queryRefreshing the page reopens an old create or alert actionConsume the query after the action or detail view opens
Analytics filters reach only one card or exportMetrics disagree within the same reportKeep sanitized filter state in the URL and pass it to every report surface
Live analytics polling continues while the page is hiddenThe Console spends resources on data the user cannot seePoll only while the document is visible
Review history is removed with the current repositoryProject review history disappears after repository cleanupKeep enrollment state separate from completed review records

Key files

FileWhy to read it
apps/…/RequireAuth.tsxShared account guard, optional-auth routes, MFA, verification, blocked accounts, and redirects
apps/…/post-auth-navigation.tsSafe destinations after authentication
apps/…/auth.magic-url.tsxMagic URL session creation and account switching
apps/…/verify-email.tsxVerification confirmation, resend behavior, and post-verification routing
apps/…/View.tsxOrganization tabs, role-aware access, project lists, pins, and project creation
apps/…/ProjectSelector.tsxOrganization and project switching, search, pins, scope, and creation entry points
apps/…/EnvironmentSwitcher.tsxProduction and environment context, ordering, limits, and actions
apps/…/projects.$projectId.tsxProject access state, shell setup, scope, and status curtains
apps/…/Overview.tsxProject identity, usage charts, applications, API keys, and overview actions
apps/…/View.tsxAuth tabs, URL-backed users and teams lists, filters, creation, and access gates
apps/…/Templates.tsxAuthentication email template types, locales, SMTP dependency, and editing flow
apps/…/VerifyDomainContent.tsxShared DNS verification states and domain targets
apps/…/GitSettingsCard.tsxGit connection lifecycle and recovery when provider data is unavailable
apps/…/CreateSiteView.tsxSite creation choices, repository import, templates, and manual upload entry
apps/…/AnalyticsCard.tsxSite analytics behavior and production tracking setup
apps/…/Layout.tsxVideo detail navigation, readiness state, access gates, and create actions
apps/…/View.tsxVideo list, filtering, sorting, paging, empty states, and bulk actions
apps/…/View.tsxCaption list, upload, creation, download, and delete flow
apps/…/SubtitleEditor.tsxCaption editing, playback, file import and export, validation, save, and unsaved-work protection
apps/…/Layout.tsxUsage categories, filters, retention, firewall prefill, and monitor entry points
apps/…/Layout.tsxMonitor and alert navigation with active firing counts
apps/…/projects.$projectId.monitors.index.tsxMonitor creation prefill, plan limit, and access behavior
apps/…/View.tsxReview history, repositories, learnings, performance, paging, and access gates
apps/…/Performance.tsxReview performance metrics and repository or date-range analysis
apps/…/SessionMigrationsContext.tsxSession-scoped progress for long-running project work