PKCE flow

The Proof Key for Code Exchange (PKCE) flow is one of two ways that a user can authenticate and your app can receive the necessary access and refresh tokens.

The flow is an implementation detail handled for you by Supabase Auth, but understanding the difference between PKCE and implicit flow is important for understanding the difference between client-only and server-side auth.

How it works#

After a successful verification, the user is redirected to your app with a URL that looks like this:

1
https://yourapp.com/...?code=<...>

The code parameter is commonly known as the Auth Code and can be exchanged for an access token by calling exchangeCodeForSession(code).

As the flow is run server side, localStorage may not be available. You may configure the client library to use a custom storage adapter and an alternate backing storage such as cookies by setting the storage option to an object with the following methods:

1
import { type SupportedStorage } from '@supabase/supabase-js';
2
const supportsLocalStorage = () => true
3
4
// ---cut---
5
const customStorageAdapter: SupportedStorage = {
6
    getItem: (key) => {
7
    if (!supportsLocalStorage()) {
8
        // Configure alternate storage
9
        return null
10
    }
11
    return globalThis.localStorage.getItem(key)
12
    },
13
    setItem: (key, value) => {
14
    if (!supportsLocalStorage()) {
15
        // Configure alternate storage here
16
        return
17
    }
18
    globalThis.localStorage.setItem(key, value)
19
    },
20
    removeItem: (key) => {
21
    if (!supportsLocalStorage()) {
22
        // Configure alternate storage here
23
        return
24
    }
25
    globalThis.localStorage.removeItem(key)
26
    },
27
}

You may also configure the client library to automatically exchange it for a session after a successful redirect. This can be done by setting the detectSessionInUrl option to true.

Putting it all together, your client library initialization may look like this:

1
import { createClient } from '@supabase/supabase-js'
2
3
// ---cut---
4
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...', {
5
  // ...
6
  auth: {
7
    // ...
8
    detectSessionInUrl: true,
9
    flowType: 'pkce',
10
    storage: {
11
      getItem: () => Promise.resolve('FETCHED_TOKEN'),
12
      setItem: () => {},
13
      removeItem: () => {},
14
    },
15
  },
16
  // ...
17
})

Limitations#

Behind the scenes, the code exchange requires a code verifier. Both the code in the URL and the code verifier are sent back to the Auth server for a successful exchange.

The code verifier is created and stored locally when the Auth flow is first initiated. That means the code exchange must be initiated on the same browser and device where the flow was started.

Overlapping flows#

If more than one PKCE flow is started on the same browser before either one completes (for example, signInWithOAuth() called in two tabs), the code verifier stored for the earlier flow is overwritten by the later one, and exchanging the first flow's code fails.

To keep each flow's verifier separate, set the appendPkceFlowIdToRedirects option when creating the client:

1
const supabase = createClient(supabaseUrl, supabaseKey, {
2
  auth: {
3
    experimental: { appendPkceFlowIdToRedirects: true },
4
  },
5
})

With this enabled, the client library appends a sb_flow_id query parameter to redirectTo, so your OAuth callback page can read it back and use it to select the matching verifier. You can also get the flow ID directly from the response of signInWithOAuth():

1
const { data, error } = await supabase.auth.signInWithOAuth({
2
  provider: 'github',
3
})
4
5
const flowId = data.flowId

Pass the flow ID to exchangeCodeForSession() to make sure the correct verifier is used, whether you read it from data.flowId or from the sb_flow_id query parameter in the redirect URL:

1
const { data, error } = await supabase.auth.exchangeCodeForSession(authCode, { flowId })

Resources#

• OAuth 2.0 guide to PKCE flow