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.

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.

   Node.js

   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

   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

   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 := scalekit.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

   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

Which endpoint should I use for logout?

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

Why must logout be a browser redirect?

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:

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:

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.

Session not clearing after logout?

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.