# Implement logout

When implementing logout functionality, you need to consider three session layers where user authentication state is maintained:

1. **Application session layer**: Your application stores session tokens (access tokens, refresh tokens, ID tokens) in browser cookies. You control this layer completely.

2. **Scalekit session layer**: Scalekit maintains a session for the user and stores their information. When users return to Scalekit's authentication page, their information is remembered for a smoother experience.

3. **Identity provider session layer**: When users authenticate with external providers (for example, Okta through enterprise SSO), those providers maintain their own sessions. Users won't be prompted to sign in again if they're already signed into the provider.

This guide shows you how to clear the application session layer and invalidate the Scalekit session layer in a single logout endpoint.

![Logout flow showing three session layers](@/assets/docs/fsa/logout/1.png)

1. ## Create a logout endpoint

   Create a `/logout` endpoint in your application that handles the complete logout flow: extracting the ID token, generating the Scalekit logout URL (which points to Scalekit's `/oidc/logout` endpoint), clearing session cookies, and redirecting to Scalekit.

    ```javascript title="Express.js"
        app.get('/logout', (req, res) => {
          // Step 1: Extract the ID token (needed for Scalekit logout)
          const idTokenHint = req.cookies.idToken;
          const postLogoutRedirectUri = 'http://localhost:3000/login';

          // Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
          const logoutUrl = scalekit.getLogoutUrl(
            idTokenHint, // ID token to invalidate
            postLogoutRedirectUri // URL that scalekit redirects after session invalidation
          );

          // Step 3: Clear all session cookies
          res.clearCookie('accessToken');
          res.clearCookie('refreshToken');
          res.clearCookie('idToken'); // Clear AFTER using it for logout URL

          // Step 4: Redirect to Scalekit to invalidate the session
          res.redirect(logoutUrl);
        });
        ```
      ```python title="Flask"
        from flask import request, redirect, make_response
        from scalekit import LogoutUrlOptions

        @app.route('/logout')
        def logout():
            # Step 1: Extract the ID token (needed for Scalekit logout)
            id_token = request.cookies.get('idToken')
            post_logout_redirect_uri = 'http://localhost:3000/login'

            # Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
            logout_url = scalekit_client.get_logout_url(
                LogoutUrlOptions(
                    id_token_hint=id_token,
                    post_logout_redirect_uri=post_logout_redirect_uri
                )
            )

            # Step 3: Create response and clear all session cookies
            response = make_response(redirect(logout_url))
            response.set_cookie('accessToken', '', max_age=0)
            response.set_cookie('refreshToken', '', max_age=0)
            response.set_cookie('idToken', '', max_age=0)  # Clear AFTER using it for logout URL

            # Step 4: Return response that redirects to Scalekit
            return response
        ```
      ```go title="Gin"
        func logoutHandler(c *gin.Context) {
            // Step 1: Extract the ID token (needed for Scalekit logout)
            idToken, _ := c.Cookie("idToken")
            postLogoutRedirectURI := "http://localhost:3000/login"

            // Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
            logoutURL, err := scalekitClient.GetLogoutUrl(LogoutUrlOptions{
                IdTokenHint: idToken,
                PostLogoutRedirectUri: postLogoutRedirectURI,
            })
            if err != nil {
                c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
                return
            }

            // Step 3: Clear all session cookies
            c.SetCookie("accessToken", "", -1, "/", "", true, true)
            c.SetCookie("refreshToken", "", -1, "/", "", true, true)
            c.SetCookie("idToken", "", -1, "/", "", true, true)  // Clear AFTER using it for logout URL

            // Step 4: Redirect to Scalekit to invalidate the session
            c.Redirect(http.StatusFound, logoutURL.String())
        }
        ```
      ```java title="Spring Boot"
        @GetMapping("/logout")
        public void logout(HttpServletRequest request, HttpServletResponse response) throws IOException {
            // Step 1: Extract the ID token (needed for Scalekit logout)
            String idToken = request.getCookies() != null ?
                Arrays.stream(request.getCookies())
                    .filter(c -> c.getName().equals("idToken"))
                    .findFirst()
                    .map(Cookie::getValue)
                    .orElse(null) : null;

            String postLogoutRedirectUri = "http://localhost:3000/login";

            // Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint)
            LogoutUrlOptions options = new LogoutUrlOptions();
            options.setIdTokenHint(idToken);
            options.setPostLogoutRedirectUri(postLogoutRedirectUri);
            URL logoutUrl = scalekitClient.authentication().getLogoutUrl(options);

            // Step 3: Clear all session cookies with security attributes
            Cookie accessTokenCookie = new Cookie("accessToken", null);
            accessTokenCookie.setMaxAge(0);
            accessTokenCookie.setPath("/");
            accessTokenCookie.setHttpOnly(true);
            accessTokenCookie.setSecure(true);
            response.addCookie(accessTokenCookie);

            Cookie refreshTokenCookie = new Cookie("refreshToken", null);
            refreshTokenCookie.setMaxAge(0);
            refreshTokenCookie.setPath("/");
            refreshTokenCookie.setHttpOnly(true);
            refreshTokenCookie.setSecure(true);
            response.addCookie(refreshTokenCookie);

            Cookie idTokenCookie = new Cookie("idToken", null);
            idTokenCookie.setMaxAge(0);
            idTokenCookie.setPath("/");
            idTokenCookie.setHttpOnly(true);
            idTokenCookie.setSecure(true);
            response.addCookie(idTokenCookie);  // Clear AFTER using it for logout URL

            // Step 4: Redirect to Scalekit to invalidate the session
            response.sendRedirect(logoutUrl.toString());
        }
        ```
      The logout flow clears cookies **AFTER** extracting the ID token and generating the logout URL. This ensures the ID token is available for Scalekit's logout endpoint.
**Why must logout be a browser redirect?:** You must redirect to the `/oidc/logout` endpoint using a **browser redirect**, not through an API call. Redirecting the browser to Scalekit's logout URL ensures the session cookie is automatically sent with the request, allowing Scalekit to correctly identify and end the user's session.

2.  ## Configure post-logout redirect URL

    After users log out, Scalekit redirects them to the URL you specify in the `post_logout_redirect_uri` parameter. This URL must be registered in your Scalekit dashboard under **Dashboard > Authentication > Redirects > Post Logout URL**.

    Scalekit only redirects to URLs from your allow list. This prevents unauthorized redirects and protects your users. If you need different redirect URLs for different applications, you can register multiple post-logout URLs in your dashboard.
**Logout security checklist:** - Extract the ID token BEFORE clearing cookies (needed for Scalekit logout)
- Clear all session cookies from your application
- Redirect to Scalekit's logout endpoint to invalidate the session server-side
- Ensure your post-logout redirect URI is registered in the Scalekit dashboard

## Common logout scenarios

<details>
<summary>Which endpoint should I use for logout?</summary>

Use `/oidc/logout` (end_session_endpoint) for user logout functionality. This endpoint requires a browser redirect and clears the user's session server-side.

</details>

<details>
<summary>Why must logout be a browser redirect?</summary>

You need to route to the `/oidc/logout` endpoint through a **browser redirect**, not with an API request. Redirecting the browser to Scalekit's logout URL ensures the session cookie is sent automatically, so Scalekit can correctly locate and end the user's session.

**❌ Doesn't work - API call from frontend:**
```javascript
fetch('https://your-env.scalekit.dev/oidc/logout', {
  method: 'POST',
  body: JSON.stringify({ id_token_hint: idToken })
});
// Session cookie is NOT included, Scalekit can't identify the session
```

**✅ Works - Browser redirect:**
```javascript
const logoutUrl = scalekit.getLogoutUrl(idToken, postLogoutRedirectUri);
window.location.href = logoutUrl;
// Browser includes session cookies automatically
```

**Why:** Your user session is stored in an HttpOnly cookie. API requests from JavaScript or backend servers don't include this cookie, so Scalekit can't identify which session to terminate.

</details>

<details>
<summary>Session not clearing after logout?</summary>

If clicking login after logout bypasses the login screen and logs you back in automatically, check the following:

1. **Verify the logout method** - Open browser DevTools → Network tab and trigger logout:
   - ✅ Type should show **"document"** (navigation)
   - ❌ Type should **NOT** show "fetch" or "xhr"
   - Check that the `Cookie` header is present in the request

2. **Check post-logout redirect URI** - Ensure it's registered in **Dashboard > Authentication > Redirects > Post Logout URL**.

</details>