Appwrite Authentication: JWT vs External OAuth2 in 0.21+

Choose Appwrite Authentication: Built-in JWT or External OAuth2

The decision is whether to use Appwrite's built-in signed JWT authentication or connect an external OAuth2 provider. The useful takeaway: use JWT for fast setup and automatic session handling; choose OAuth2 when compliance requires provider-level MFA or audit logs.

Decision Constraints

This guide assumes Appwrite version 0.21 or later. Appwrite Auth issues signed JSON Web Tokens (JWTs) stored in HttpOnly cookies and refreshes them automatically. External OAuth2 means registering a third-party provider through Appwrite's Authentication API and handling the authorization-code exchange manually.

Supported Options Comparison

Feature	JWT Auth (Appwrite Auth)	External OAuth2
Default state	Enabled out of the box	Requires provider registration
Token handling	Signed JWT in HttpOnly cookie; auto-refreshes	Authorization-code exchange; manual renewal
Setup effort	Minimal; set secret and expiry	Higher; register provider and redirect URI
Security depth	Relies on Appwrite key rotation; custom revocation needed	Provider MFA and audit logs

Trade-offs

JWT authentication works immediately with all SDKs. Its main constraint is clock synchronization: mismatched client and server clocks cause token validation failure, and expiration is controlled only by an environment variable.

External OAuth2 offers stronger security context but adds complexity. The authorized redirect URI in the Appwrite console must exactly match the client callback URL, or the flow is rejected.

Concrete Validation: Confirm JWT Session

Run these checks against a running Appwrite instance. You need access to the Appwrite CLI or server environment, and permission to restart services if you change environment variables.

1. Check version: Run appwrite info in the Appwrite CLI. Confirm the reported version is 0.21 or higher and that Auth is enabled.
2. Set the signing secret: Export APPWRITE_JWT_SECRET=replace-with-a-strong-secret in the Appwrite server environment, then restart Appwrite services. Risk: a missing or incorrect secret prevents cookie issuance. Rollback: restore the previous secret value and restart services.
3. Request a JWT: Execute curl -i https://your-app.example.com/auth/jwt from a client machine. Expected check: the response headers include Set-Cookie with an HttpOnly JWT.
4. Retrieve the session: In your application code, call account.getSession('JWT') using the Appwrite SDK. Expected result: a user object is returned without an authentication error.

If the cookie is absent, verify that the secret was loaded and the container restarted. For OAuth2, send a mock authorization code to Appwrite's callback endpoint and confirm a valid access token is returned.

Limitations

• JWT does not provide native MFA; revocation requires custom server-side logic such as a token blocklist.
• OAuth2 fails if the registered redirect URI does not exactly match the client callback URL.
• Mixing JWT and OAuth2 in one project requires custom middleware to reconcile user records.

Practical Result Check

After configuration, a successful sign-in should set the HttpOnly cookie and allow account.getSession('JWT') to return the current user. For OAuth2, a successful authorization-code exchange should return an access token from Appwrite's callback endpoint.