Add “Login with idpass” to your portal

A verified-human login button — like “Login with Google”, but the person is KYC-verified on their own phone. You never store passwords or handle Aadhaar.

What happens when someone logs in

Step 0 — get your keys

1. Create a free account.
2. Copy your Client ID (looks like idp_ab12cd34…) — and the secret if it’s a server-side app.
3. Pick an integration path below.

Option A — Drop-in button easiest

No backend needed. Register a “App with no server” at signup. Two lines add this button:

🔐 Login with idpass  ← this is what your users see

<script src="https://idpass.in/sdk/idpass.js"
        data-client-id="idp_YOUR_ID"
        data-redirect-uri="https://your-site.com/callback"
        data-button="#idpass-login"></script>
<div id="idpass-login"></div>

<script src="https://idpass.in/sdk/idpass.js"
        data-client-id="idp_YOUR_ID"
        data-redirect-uri="https://your-site.com/callback"></script>
<script>
  const res = await idpass.handleRedirect();      // null if no login in progress
  if (res) {
    console.log("Signed in as", res.claims.name); // verified name
    // res.claims = { sub, name, dob_verified, loa, ... }
    // now create a session for res.claims.sub on your side
  }
</script>

The SDK handles the secure exchange, verifies the token, and only works from the web address you registered. That’s the whole integration.

Option B — Server-side any language

Register a “Normal website” (you get a secret). Point any OpenID Connect library at our discovery URL — done.

Discovery URL: https://atithipass.com/portal/.well-known/openid-configuration

import { Issuer, generators } from "openid-client";
const iss = await Issuer.discover("https://idpass.in");
const client = new iss.Client({
  client_id: "idp_YOUR_ID", client_secret: "YOUR_SECRET",
  redirect_uris: ["https://your-site.com/callback"], response_types: ["code"],
});
// start login
const cv = generators.codeVerifier(); req.session.cv = cv;
res.redirect(client.authorizationUrl({
  scope: "openid profile",
  code_challenge: generators.codeChallenge(cv), code_challenge_method: "S256",
}));
// on /callback
const params = client.callbackParams(req);
const tokenSet = await client.callback("https://your-site.com/callback", params,
  { code_verifier: req.session.cv });
const user = tokenSet.claims();   // { sub, name, dob_verified, loa, ... }

from authlib.integrations.flask_client import OAuth
oauth = OAuth(app)
oauth.register(name="idpass",
    server_metadata_url="https://idpass.in/.well-known/openid-configuration",
    client_id="idp_YOUR_ID", client_secret="YOUR_SECRET",
    client_kwargs={"scope": "openid profile", "code_challenge_method": "S256"})

@app.route("/login")
def login():
    return oauth.idpass.authorize_redirect("https://your-site.com/callback")

@app.route("/callback")
def callback():
    token = oauth.idpass.authorize_access_token()
    user = token["userinfo"]      # { sub, name, dob_verified, loa, ... }
    return f"Hello {user['name']}"

Option C — Key pair extra-secure

For developers/fintechs who prefer no shared secret. Register an “Extra-secure (key pair)” app and paste your public key. Make one in 30 seconds:

openssl genrsa -out my_private_key.pem 2048
openssl rsa -in my_private_key.pem -pubout -out my_public_key.pem
cat my_public_key.pem     # paste this output at signup

Keep my_private_key.pem secret on your server. Your OIDC library signs a short “client assertion” with it — no secret ever leaves your machine.

Option D — Raw HTTP no library · any stack

Wiring it by hand — PHP, Go, or any stack without an OIDC library? idpass is plain OpenID Connect (Authorization Code + PKCE). Four HTTP steps, no magic. This is the section to read if your callback gave you a code and state and you’re not sure what to do next.

Step 1 — send the user to authorize (build PKCE)

Generate a random state and a PKCE code_verifier; the code_challenge is its SHA-256. Keep the verifier in the user’s session — you need it again in Step 3.

https://idpass.in/oidc/authorize
  ?client_id=idp_YOUR_ID
  &redirect_uri=https://your-site.com/callback   # must match a registered URI exactly
  &response_type=code
  &scope=openid%20profile
  &state=RANDOM_STATE                            # you generate; compared in step 2
  &nonce=RANDOM_NONCE                            # you generate; compared in step 4
  &code_challenge=BASE64URL( SHA256(code_verifier) )
  &code_challenge_method=S256                    # PKCE is mandatory

function b64url($b){ return rtrim(strtr(base64_encode($b),'+/','-_'),'='); }
$_SESSION['state']    = b64url(random_bytes(16));
$_SESSION['nonce']    = b64url(random_bytes(16));
$_SESSION['verifier'] = b64url(random_bytes(32));
$challenge = b64url(hash('sha256', $_SESSION['verifier'], true));  // raw=true, then b64url
$url = "https://idpass.in/oidc/authorize?".http_build_query([
  "client_id"=>"idp_YOUR_ID","redirect_uri"=>"https://your-site.com/callback",
  "response_type"=>"code","scope"=>"openid profile",
  "state"=>$_SESSION['state'],"nonce"=>$_SESSION['nonce'],
  "code_challenge"=>$challenge,"code_challenge_method"=>"S256"]);
header("Location: $url");

Step 2 — the user comes back to your callback

After they approve on their phone, idpass redirects to your redirect_uri with two query params. First check state equals what you stored (CSRF protection) — if not, stop.

code  = code_ADBC53QWgSoqsJwzz2xQYno6Fox9AV9J   # one-time; swap it in step 3
state = w2UJuW6_6faWwfNQDOTV6g                   # must equal $_SESSION['state']

Step 3 — exchange the code for tokens

POST to the token endpoint with the code and the same code_verifier from Step 1. Send client_secret too if yours is a server-side (“Normal website”) app.

curl -s https://idpass.in/oidc/token \
  -d grant_type=authorization_code \
  -d code=code_ADBC53QWgSoqsJwzz2xQYno6Fox9AV9J \
  -d redirect_uri=https://your-site.com/callback \
  -d client_id=idp_YOUR_ID \
  -d client_secret=YOUR_SECRET \        # omit only for a public (no-server) app
  -d code_verifier=THE_SAME_VERIFIER_FROM_STEP_1

$ch = curl_init("https://idpass.in/oidc/token");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER=>true,
  CURLOPT_POST=>true,
  CURLOPT_POSTFIELDS=>http_build_query([
    "grant_type"=>"authorization_code",
    "code"=>$_GET['code'],
    "redirect_uri"=>"https://your-site.com/callback",
    "client_id"=>"idp_YOUR_ID",
    "client_secret"=>"YOUR_SECRET",           // omit for a public app
    "code_verifier"=>$_SESSION['verifier'],   // the one you stored in step 1
  ]),
]);
$tok = json_decode(curl_exec($ch), true);
// $tok = ["access_token"=>..., "id_token"=>"eyJ...", "expires_in"=>3600, ...]

const r = await fetch("https://idpass.in/oidc/token", {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: req.query.code,
    redirect_uri: "https://your-site.com/callback",
    client_id: "idp_YOUR_ID",
    client_secret: "YOUR_SECRET",             // omit for a public app
    code_verifier: req.session.verifier,      // the one from step 1
  }),
});
const tok = await r.json();   // { access_token, id_token, expires_in, ... }

The response is JSON: { "access_token": "…", "id_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }.

Step 4 — read the user (decode & verify the id_token)

Verify the id_token signature against our JWKS (algorithm RS256), then its payload is your verified user. Also confirm nonce matches what you sent, and aud equals your client_id.

use Firebase\JWT\JWT;
use Firebase\JWT\JWK;
$jwks = json_decode(file_get_contents("https://idpass.in/oidc/jwks.json"), true);
$claims = JWT::decode($tok['id_token'], JWK::parseKeySet($jwks));   // verifies RS256 signature
// $claims is your user:
//   $claims->name, $claims->dob_verified, $claims->loa,
//   $claims->sub  (stable id, unique to YOUR app), $claims->unique_id
if ($claims->aud !== "idp_YOUR_ID")        die("wrong audience");
if ($claims->nonce !== $_SESSION['nonce']) die("nonce mismatch");
// -> log the user in as $claims->sub

import jwt
from jwt import PyJWKClient
jwks = PyJWKClient("https://idpass.in/oidc/jwks.json")
key = jwks.get_signing_key_from_jwt(tok["id_token"]).key
claims = jwt.decode(tok["id_token"], key, algorithms=["RS256"],
                    audience="idp_YOUR_ID", issuer="https://idpass.in")
# claims == { "name": "...", "dob_verified": True, "loa": 2,
#             "sub": "...", "unique_id": "...", "device_bound": True, ... }

Prefer an API call over decoding? Send the access_token (not the id_token) as a Bearer token to https://atithipass.com/portal/oidc/userinfo and it returns { sub, name, dob_verified, loa }.

Stuck? Common errors

What you receive

Optional fields (with user consent)

Beyond the base identity, you can request additional verified fields by adding scopes. At sign-in the user sees a per-field toggle and chooses what to share — so a field arrives only if the user consents. If they decline, the claim is simply absent (design your flow to handle that).

scope=openid%20profile%20idpass:address%20idpass:aadhaar_last4

The full Aadhaar number is never shared — only the masked last-4. The scope in the token response tells you which optional fields the user actually granted. Users can also present single facts (e.g. “over 18”) without revealing anything else.

Advanced & regulated

Need higher assurance? idpass supports bank-grade options (sender-constrained tokens, pushed requests, a regulated profile) and agent-assisted / call-centre login where the request is pushed to the user’s phone. Turn these on per app, or ask us — the discovery document lists everything a library needs automatically.

Troubleshooting

The error idpass returns tells you precisely what to fix. The two you’re most likely to hit when wiring it by hand:

Still stuck after checking the above? Send us your client_id and the time of a failed attempt — we can see the exact reason server-side and tell you which of these it is.

Prefer Postman? Import the collection above, set your client_id/secret, and run the requests.