Login and logout for web applications

The complete lifecycle for an external web application: from the first redirect to ScaiKey, through token handling, to a logout that actually logs the user out.

Read this end to end before integrating. Most integration problems we see come from one of two places — the token exchange, or treating logout as a client-side concern.

The mental model: there are two sessions#

This is the single most important idea on the page.

If you clear only your own session and redirect to your login page, the browser still holds the ScaiKey SSO cookie. Your login redirect hits /oauth/authorize, ScaiKey sees a valid session, and issues a fresh authorization code without prompting. The user is back where they started, apparently never logged out.

A logout that does not call ScaiKey's end-session endpoint is not a logout.

Before you start#

Your application must be registered with ScaiKey. Ask the platform team for:

Which endpoint family do you use?#

Pair them consistently: if you authorize against the platform endpoint, log out against the platform endpoint. Mixing families works but makes debugging harder.

Throughout this page, $SCAIKEY is https://scaikey.scailabs.ai.

Always read endpoints from discovery#

1

curl -s "$SCAIKEY/api/v1/platform/oauth/.well-known/openid-configuration" | jq

1
2
3
4
5
6
7
8

{
  "issuer": "https://scaikey.scailabs.ai/platform",
  "authorization_endpoint": "https://scaikey.scailabs.ai/api/v1/platform/oauth/authorize",
  "token_endpoint": "https://scaikey.scailabs.ai/api/v1/platform/oauth/token",
  "userinfo_endpoint": "https://scaikey.scailabs.ai/api/v1/platform/oauth/userinfo",
  "end_session_endpoint": "https://scaikey.scailabs.ai/api/v1/platform/oauth/logout",
  "jwks_uri": "https://scaikey.scailabs.ai/api/v1/platform/.well-known/jwks.json"
}

Note that issuer and the endpoint URLs have different base paths. That is deliberate: issuer must equal the iss claim we mint into tokens, while the endpoints live under the API prefix. Validate iss against issuer; send requests to the endpoint URLs. Do not construct endpoint URLs by appending to issuer.

Part 1 — Login#

Step 1: Generate PKCE values#

Required for public clients (SPAs, mobile), recommended for everyone.

1
2
3
4
5
6

import base64, hashlib, secrets

verifier  = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
challenge = base64.urlsafe_b64encode(
    hashlib.sha256(verifier.encode()).digest()
).rstrip(b"=").decode()

Store verifier in the user's pre-login session. You need it at Step 4.

Step 2: Redirect to the authorize endpoint#

1
2
3
4
5
6
7
8

GET $SCAIKEY/api/v1/platform/oauth/authorize
  ?response_type=code
  &client_id=<your client_id>
  &redirect_uri=https%3A%2F%2Fyourapp.example%2Fauth%2Fcallback
  &scope=openid%20profile%20email
  &state=<random, stored in session>
  &code_challenge=<challenge>
  &code_challenge_method=S256

If the user already has a valid SSO session, ScaiKey returns a code immediately without showing a login screen. That is single sign-on working as intended.

Step 3: Handle the callback#

We redirect to your redirect_uri with code and state.

Verify state matches the value you stored. If it does not, abort — do not exchange the code.

Step 4: Exchange the code for tokens#

Server-side, within about 60 seconds. Codes are single-use.

1
2
3
4
5
6
7
8

curl -X POST "$SCAIKEY/api/v1/platform/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "redirect_uri=https://yourapp.example/auth/callback" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "code_verifier=$VERIFIER"

1
2
3
4
5
6
7
8

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "3f9a…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

redirect_uri must be identical to the one from Step 2 — it is verified, not decorative.

Step 5: Validate the ID token#

Before trusting any claim:

1. Verify the signature against jwks_uri (cache the keys; honour kid).
2. Check iss equals the issuer from discovery — exactly, no normalisation.
3. Check aud contains your client_id.
4. Check exp is in the future.
5. If you sent nonce, check it matches.

Claims you can expect:

Step 6: Establish your own session — and store the ID token#

Create your application session now. Persist the raw id_token alongside it. You need it at logout as id_token_hint, and it is the most common thing teams forget.

1
2
3

session["user_id"]  = claims["sub"]
session["email"]    = claims["email"]
session["id_token"] = tokens["id_token"]   # required for a correct logout

Part 2 — Using and refreshing tokens#

Send the access token to resource servers:

1

Authorization: Bearer <access_token>

When it expires, use the refresh token:

1
2
3
4
5
6

curl -X POST "$SCAIKEY/api/v1/platform/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

Refresh tokens rotate: each refresh returns a new one and retires the old. Store the new value immediately.

A refresh token is bound to the SSO session that created it. When that session ends — because the user logged out, an administrator revoked it, or it expired — the refresh token is revoked with it and further refreshes fail with invalid_grant. Treat that as "the user must log in again", not as an error to retry.

Part 3 — Logout#

The complete sequence#

1. Clear your own application session.
2. Redirect the browser to the end-session endpoint, with id_token_hint.
3. We terminate the SSO session, revoke refresh tokens, and clear our cookie.
4. We redirect the browser back to your post_logout_redirect_uri.

1
2
3
4

GET $SCAIKEY/api/v1/platform/oauth/logout
  ?id_token_hint=<the id_token you stored at Step 6>
  &post_logout_redirect_uri=https%3A%2F%2Fyourapp.example%2Flogin%3Flogged_out%3D1
  &state=<optional>

Make sure you have the right endpoint#

ScaiKey has several routes with "logout" in the path. Only two are OIDC end-session endpoints, and only those accept a browser redirect:

The distinguishing feature is the oauth/ segment. If you send a browser to one of the POST routes you will get 405 Method Not Allowed with Allow: POST, and — because the navigation fails quietly — a logout that appears to do nothing.

Take the URL from end_session_endpoint in the discovery document and this cannot happen.

Two rules people get wrong#

Redirect the browser. Do not call this from your server. The endpoint identifies the session from the browser's SSO cookie. A back-channel HTTP call from your backend carries no cookie, ends nothing, and returns a redirect your server then discards. The user stays signed in.

Clearing your session is not enough on its own. See The mental model at the top.

What logout does and does not do#

Because access tokens survive, keep their lifetime short if logout needs to take effect quickly, and use introspection at resource servers when you need certainty:

1
2

curl -X POST "$SCAIKEY/api/v1/auth/tenants/{slug}/oauth/introspect" \
  -u "$CLIENT_ID:$CLIENT_SECRET" -d "token=$ACCESS_TOKEN"

Post-logout redirects#

post_logout_redirect_uri is validated. An unaccepted value is ignored and the user lands on ScaiKey's generic signed-out page instead of returning to your application.

A value is accepted when it either:

• exactly matches one of your registered logout_uris, or
• shares an origin (scheme + host + port) with one of your registered redirect_uris.

Matching is exact. https://app.example.com does not authorise:

If you send id_token_hint or client_id, we check against that application alone. If you send neither, we check against every active application in scope — the redirect still works, but we cannot revoke your client's tokens by client. Send id_token_hint.

Register an explicit logout_uri only when your signed-out page lives on a different origin than your OAuth callback.

Worked example (Flask)#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from flask import Flask, redirect, session, request
from urllib.parse import urlencode

SCAIKEY = "https://scaikey.scailabs.ai/api/v1/platform"

@app.route("/auth/callback")
def callback():
    tokens = exchange_code(request.args["code"])      # Steps 3-4
    claims = validate_id_token(tokens["id_token"])    # Step 5
    session["user_id"]  = claims["sub"]
    session["id_token"] = tokens["id_token"]          # keep it for logout
    return redirect("/dashboard")

@app.route("/auth/logout")
def logout():
    id_token = session.get("id_token")
    session.clear()                                   # 1. end your session
    params = urlencode({                              # 2. end ours
        "id_token_hint": id_token or "",
        "post_logout_redirect_uri": "https://yourapp.example/login?logged_out=1",
    })
    return redirect(f"{SCAIKEY}/oauth/logout?{params}")

Federated logins#

When a user signs in through an external identity provider (OIDC or SAML), ScaiKey still creates its own SSO session, and everything above applies unchanged.

One caveat: logging out of ScaiKey does not log the user out of the upstream IdP. If that IdP still holds a session, clicking its button again may sign the user straight back in without a prompt. When you need both ended, call the IdP's own end-session endpoint after ours.

Integration checklist#

• Endpoints read from the discovery document, not hardcoded
• iss validated against issuer from discovery, aud against your client_id
• state verified on the callback
• PKCE used (mandatory for public clients)
• sub used as the user key, not email
• id_token stored at login for use at logout
• Logout clears your session and redirects to the end-session endpoint
• Logout is a browser redirect, not a server-side call
• post_logout_redirect_uri on a registered origin
• Rotated refresh tokens persisted on every refresh
• invalid_grant on refresh handled as "log in again"

Troubleshooting#