Skip to Content
DocsQuickstart guidesPython (Flask)

Python (Flask) quickstart

🔑 Auth: client_id + client_secret (server-side) · 👤 This IS the login — standard OpenID Connect · 🐍 Raw API recipe · ⏱ ~10 minutes

What you’ll build: a two-route Flask app where “Connect with Valyd” returns the user’s pseudonymous valyd_id to your backend — no SDK, just requests.

Your real values are on your app’s API keys page in the Developer Portal .

1. Create the app

In the Developer Portal  create an application, enable the profile scope, and register this exact redirect URI:

http://localhost:5000/callback

Copy the client_id and the one-time client_secret.

2. Install

mkdir valyd-login && cd valyd-login pip install flask requests

Export your credentials (replace with the real values from the portal):

export VALYD_CLIENT_ID=YOUR_CLIENT_ID export VALYD_CLIENT_SECRET=YOUR_CLIENT_SECRET export VALYD_REDIRECT_URI=http://localhost:5000/callback export SESSION_SECRET=replace_with_at_least_32_random_characters

3. Write the app

app.py

import base64 import hashlib import os import secrets from urllib.parse import urlencode import requests from flask import Flask, abort, redirect, request, session VALYD = "https://idp.valyd.work" app = Flask(__name__) app.secret_key = os.environ["SESSION_SECRET"] @app.route("/") def home(): return '<a href="/login">Connect with Valyd</a>' @app.route("/login") def login(): state = secrets.token_hex(16) # CSRF: Valyd echoes it back on the callback nonce = secrets.token_hex(16) # bound into the id_token (replay protection) # PKCE (required for every client): keep the verifier, send its S256 hash code_verifier = secrets.token_urlsafe(48) code_challenge = base64.urlsafe_b64encode( hashlib.sha256(code_verifier.encode()).digest() ).rstrip(b"=").decode() session["valyd_state"] = state session["valyd_nonce"] = nonce session["valyd_code_verifier"] = code_verifier return redirect(f"{VALYD}/api/auth/oidc/authorize?" + urlencode({ "client_id": os.environ["VALYD_CLIENT_ID"], "redirect_uri": os.environ["VALYD_REDIRECT_URI"], # must exactly match an app redirect URI "response_type": "code", "scope": "openid profile", # openid is REQUIRED "state": state, "nonce": nonce, "code_challenge": code_challenge, "code_challenge_method": "S256", })) @app.route("/callback") def callback(): if "error" in request.args: # e.g. access_denied (user pressed Cancel), login_required return {"error": request.args["error"], "error_description": request.args.get("error_description", "")}, 400 if "code" not in request.args: abort(400) if not secrets.compare_digest( session.pop("valyd_state", ""), request.args.get("state", "") ): abort(400) # CSRF check — never skip it if request.args.get("iss", VALYD) != VALYD: abort(400) # RFC 9207 mix-up defence token = requests.post(f"{VALYD}/api/auth/oidc/token", data={ # form-encoded "grant_type": "authorization_code", "code": request.args["code"], "client_id": os.environ["VALYD_CLIENT_ID"], "client_secret": os.environ["VALYD_CLIENT_SECRET"], "redirect_uri": os.environ["VALYD_REDIRECT_URI"], # same URI used at authorize "code_verifier": session.pop("valyd_code_verifier", ""), # PKCE }) tokens = token.json() # TOP-LEVEL: access_token, refresh_token, id_token, expires_in (3600) if token.status_code != 200: # RFC 6749 §5.2: {"error": "invalid_grant", "error_description": "..."} return {"error": tokens.get("error"), "error_description": tokens.get("error_description")}, 400 user = requests.get( f"{VALYD}/api/auth/oidc/userinfo", headers={"Authorization": f"Bearer {tokens['access_token']}"}, ).json() # user["valyd_id"] is the stable pseudonymous ID — # find-or-create your local user against it, then start your own session. return {"valyd_id": user["valyd_id"], "id_verified": user["id_verified"]} if __name__ == "__main__": app.run(port=5000)

The id_token is an RS256-signed JWT. This quickstart trusts it because it arrived over TLS directly from the token endpoint; for production, verify its signature against the JWKS at https://idp.valyd.work/api/auth/oidc/jwks.json and check that its nonce claim equals session["valyd_nonce"] (PyJWT does both), or use an OIDC library — see Use any OIDC library.

4. Run it

python app.py

Open http://localhost:5000  and click Connect with Valyd.

✅

Checkpoint: /login redirects to https://idp.valyd.work/api/auth/oidc/authorize?... with state, nonce, code_challenge, and code_challenge_method=S256 in the URL; after consent, /callback returns your valyd_id and id_verified; and a forged callback (wrong or missing state) is rejected with HTTP 400.

Troubleshooting

  • redirect_uri mismatch — the value sent at /authorize and /token must both exactly match a registered redirect URI. See Errors & troubleshooting.
  • State check fails on legitimate logins — the Flask session cookie was lost (different host/port between login and callback, or cookies blocked); start both routes on localhost:5000. See Errors & troubleshooting.
  • invalid_scope / missing openid — scope must include openid, and every requested scope must be enabled on the app in the portal. See Errors & troubleshooting.
  • error=invalid_request on the callback — the authorize URL lacked code_challenge / code_challenge_method=S256; PKCE is required for every client.
  • invalid_grant from the token endpoint — the code was already used or expired, or the code_verifier doesn’t match the challenge. Restart from /login.

Next steps

  • Scopes — request verifications, email, or license scopes.
  • Account API — read userinfo, licenses (/api/auth/oidc/licenses), and verification proofs (/api/auth/oidc/verifications) with the access token.
  • Attach a verification — run a new KYC or license check with the user’s token so the proof saves to their Valyd account.
  • Moving to Node later? The official SDK (npm install @valyd/sdk) does this whole flow, plus PKCE and id_token verification, in two calls — see the Node.js quickstart.
Last updated on