Authorization Code with PKCE 🔐

The OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange) is the security standard for applications that cannot securely store secrets, such as Single Page Applications (SPA) or native mobile apps.

This flow adds an extra layer of security through a cryptographic “challenge” that ensures the authorization code can only be exchanged for tokens by the same client that initiated the request.

📸 Flow Overview

🛠️ Step-by-Step

Step 1: Redirect to `/authorize` endpoint

To start the OAuth 2.0 authentication flow, you must redirect the user to your Faable Auth domain. Your application needs to generate a random code_verifier and encode it as a challenge: base64UrlEncode(sha256(code_verifier)).

[!TIP] If you are using our SDK @faable/auth-js, this entire PKCE cryptographic process happens automatically and transparently.

Step 2: User Authentication

The user will see the Faable login screen and authenticate using their default connection (Email/Password, Google, GitHub, etc.).

Controlling the prompt

The optional prompt parameter on /authorize lets you control whether the user sees the login UI. It accepts a space-separated list of values:

Value	Behavior
`none`	SSO probe. No UI is ever displayed; the request errors if interaction would be needed. Cannot be combined with other values. Useful for silent re-authentication from a SPA.
`login`	Forces the user to re-authenticate, even if there’s an active session.
`consent`	Forces the consent step before issuing tokens. Currently behaves like `login` (a dedicated consent screen is on the roadmap).
`select_account`	Accepted for compatibility but currently ignored.

Unknown prompt values are accepted silently — they don’t change behavior. Most applications can leave prompt unset and rely on Faable’s default behavior.

Step 3: Callback and Code Reception

After a successful login, Faable will redirect back to your application with a code parameter in the URL:

https://your-app.com/callback?code=123456...

Step 4: Token Exchange

Your application takes that code and sends it back to Faable along with the original code_verifier to obtain the Access Token.

🚀 Quick Implementation with Faable SDK

You don’t need to worry about the technical details of PKCE; our SDK manages the entire flow for you:


import { createClient } from "@faable/auth-js";
 
const auth = createClient({
  domain: "your-domain.auth.faable.link",
  clientId: "<your_client_id>",
});
 
// Starts the process: Generates the challenge and redirects
await auth.signInWithOauthConnection({
  redirectTo: "https://your-app.com/callback",
});

[!IMPORTANT] Ensure that the redirectTo URL is configured in the Allowed Callback URLs whitelist in the Faable dashboard.

Session Auto-Refresh

One of the key benefits of using the @faable/auth-js SDK is that it automatically manages the Refresh Token flow for you. When the client is initialized, it checks the session’s validity and refreshes the Access Token transparently if it has expired.

For more details, see the Refresh Token Flow documentation.

🔗 Further Reading

@faable/auth-js : Our official JavaScript/TypeScript SDK for seamless authentication.
Refresh Token Flow: Details on how Faable Auth manages token renewal.
RFC 6749 - The OAuth 2.0 Authorization Framework : Official standard for the Authorization Code flow.
RFC 7636 - Proof Key for Code Exchange (PKCE) : Official security standard for public clients.