Developer Quickstart

Build a web app that verifies users have a biologically-anchored identity -- in under 5 minutes.

What You'll Build

By the end of this guide, your application will:

Redirect users to the BIA OIDC Provider for biological identity verification
Receive a signed id_token containing bio claims (assurance level, liveness status, biometric modalities)
Make authorization decisions based on the strength of the user's biological proof

The flow is standard OpenID Connect with BIA-specific claims -- if you've integrated Google or GitHub login, this will feel familiar.

Prerequisites

Requirement	Details
Node.js	v18+ (for JS examples) or equivalent runtime for your language
Ever BIA Developer Account	Register at developer.ever.health
HTTPS endpoint	Required for redirect URIs (use `ngrok` or `mkcert` for local dev)

No biometric hardware needed

During development, the BIA sandbox environment provides simulated biometric flows. Your users will need compatible devices in production, but you don't need anything special to integrate.

Step 1: Register Your Developer Account

Create your developer account and register your first application:

# Register as a developer
curl -X POST https://bia.ever.health/bio-oidc/developers/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@yourcompany.com",
    "organization": "Your Company",
    "password": "your-secure-password"
  }'

Response:

{
  "developer_id": "dev_8f3a1b2c4d5e",
  "api_key": "bia_dev_ak_...",
  "status": "active"
}

Now create an application:

# Create your application
curl -X POST https://bia.ever.health/bio-oidc/developers/apps \
  -H "Authorization: Bearer bia_dev_ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Health App",
    "redirect_uris": ["https://localhost:3000/callback"],
    "grant_types": ["authorization_code"],
    "bio_assurance_required": "substantial"
  }'

Response:

{
  "app_id": "app_7x9k2m4n",
  "client_id": "bia_cid_a1b2c3d4e5f6",
  "client_secret": "bia_cs_...",
  "redirect_uris": ["https://localhost:3000/callback"],
  "bio_assurance_required": "substantial",
  "created_at": "2026-04-02T10:00:00Z"
}

Keep your client_secret safe

The client_secret is shown once. Store it in an environment variable or secrets manager -- never commit it to source control.

Step 2: Install the SDK

JavaScript/TypeScript
Python
Go

npm install @ever-healthcare/bia-sdk passport passport-openidconnect express-session

pip install authlib httpx flask

go get github.com/coreos/go-oidc/v3
go get golang.org/x/oauth2

Step 3: Configure OIDC

Grab your SDK configuration from the developer portal:

curl https://bia.ever.health/bio-oidc/developers/apps/app_7x9k2m4n/sdk-config \
  -H "Authorization: Bearer bia_dev_ak_..."

{
  "issuer": "https://bia.ever.health",
  "authorization_endpoint": "https://bia.ever.health/bio-oidc/authorize",
  "token_endpoint": "https://bia.ever.health/bio-oidc/token",
  "userinfo_endpoint": "https://bia.ever.health/bio-oidc/userinfo",
  "jwks_uri": "https://bia.ever.health/.well-known/jwks.json",
  "scopes_supported": ["openid", "bio", "bio:liveness", "bio:neuro", "bio:genomic"],
  "client_id": "bia_cid_a1b2c3d4e5f6"
}

JavaScript/TypeScript (Express)
Python (Flask)
Go (net/http)

// server.ts
import express from "express";
import session from "express-session";
import passport from "passport";
import { Strategy as OIDCStrategy } from "passport-openidconnect";

const app = express();

app.use(
  session({
    secret: process.env.SESSION_SECRET!,
    resave: false,
    saveUninitialized: false,
  })
);
app.use(passport.initialize());
app.use(passport.session());

passport.use(
  "bia",
  new OIDCStrategy(
    {
      issuer: "https://bia.ever.health",
      authorizationURL: "https://bia.ever.health/bio-oidc/authorize",
      tokenURL: "https://bia.ever.health/bio-oidc/token",
      userInfoURL: "https://bia.ever.health/bio-oidc/userinfo",
      clientID: process.env.BIA_CLIENT_ID!,
      clientSecret: process.env.BIA_CLIENT_SECRET!,
      callbackURL: "https://localhost:3000/callback",
      scope: "openid bio bio:liveness",
    },
    (issuer, profile, context, idToken, accessToken, refreshToken, done) => {
      // idToken contains BIA bio claims
      return done(null, { profile, idToken });
    }
  )
);

passport.serializeUser((user, done) => done(null, user));
passport.deserializeUser((obj, done) => done(null, obj));

// Login route -- redirects to BIA OIDC Provider
app.get("/login", passport.authenticate("bia"));

// Callback route -- handles the OIDC response
app.get(
  "/callback",
  passport.authenticate("bia", { failureRedirect: "/error" }),
  (req, res) => {
    res.redirect("/dashboard");
  }
);

// Protected route
app.get("/dashboard", (req, res) => {
  if (!req.isAuthenticated()) return res.redirect("/login");

  const { idToken } = req.user as any;
  res.json({
    message: "Authenticated with biological identity",
    bio_assurance: idToken.bio_assurance_level,
    liveness: idToken.bio_liveness_active,
  });
});

app.listen(3000, () => console.log("Running on https://localhost:3000"));

# app.py
import os
from flask import Flask, redirect, url_for, session, jsonify
from authlib.integrations.flask_client import OAuth

app = Flask(__name__)
app.secret_key = os.environ["SESSION_SECRET"]

oauth = OAuth(app)
bia = oauth.register(
    name="bia",
    client_id=os.environ["BIA_CLIENT_ID"],
    client_secret=os.environ["BIA_CLIENT_SECRET"],
    server_metadata_url="https://bia.ever.health/.well-known/openid-configuration",
    client_kwargs={"scope": "openid bio bio:liveness"},
)


@app.route("/login")
def login():
    redirect_uri = url_for("callback", _external=True, _scheme="https")
    return bia.authorize_redirect(redirect_uri)


@app.route("/callback")
def callback():
    token = bia.authorize_access_token()
    id_token_claims = bia.parse_id_token(token)
    session["user"] = {
        "sub": id_token_claims["sub"],
        "bio_assurance_level": id_token_claims.get("bio_assurance_level"),
        "bio_liveness_active": id_token_claims.get("bio_liveness_active"),
        "amr": id_token_claims.get("amr", []),
    }
    return redirect("/dashboard")


@app.route("/dashboard")
def dashboard():
    user = session.get("user")
    if not user:
        return redirect("/login")
    return jsonify(
        {
            "message": "Authenticated with biological identity",
            "bio_assurance": user["bio_assurance_level"],
            "liveness": user["bio_liveness_active"],
        }
    )


if __name__ == "__main__":
    app.run(port=3000, ssl_context="adhoc")

// main.go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/coreos/go-oidc/v3/oidc"
    "golang.org/x/oauth2"
)

var (
    provider     *oidc.Provider
    oauth2Config oauth2.Config
    verifier     *oidc.IDTokenVerifier
)

func main() {
    ctx := context.Background()

    var err error
    provider, err = oidc.NewProvider(ctx, "https://bia.ever.health")
    if err != nil {
        log.Fatal(err)
    }

    oauth2Config = oauth2.Config{
        ClientID:     os.Getenv("BIA_CLIENT_ID"),
        ClientSecret: os.Getenv("BIA_CLIENT_SECRET"),
        RedirectURL:  "https://localhost:3000/callback",
        Endpoint:     provider.Endpoint(),
        Scopes:       []string{oidc.ScopeOpenID, "bio", "bio:liveness"},
    }

    verifier = provider.Verifier(&oidc.Config{ClientID: oauth2Config.ClientID})

    http.HandleFunc("/login", handleLogin)
    http.HandleFunc("/callback", handleCallback)
    log.Println("Listening on https://localhost:3000")
    log.Fatal(http.ListenAndServeTLS(":3000", "cert.pem", "key.pem", nil))
}

func handleLogin(w http.ResponseWriter, r *http.Request) {
    state := "random-state-string" // use a secure random value in production
    http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
}

func handleCallback(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    oauth2Token, err := oauth2Config.Exchange(ctx, r.URL.Query().Get("code"))
    if err != nil {
        http.Error(w, "Token exchange failed: "+err.Error(), http.StatusInternalServerError)
        return
    }

    rawIDToken, ok := oauth2Token.Extra("id_token").(string)
    if !ok {
        http.Error(w, "No id_token in response", http.StatusInternalServerError)
        return
    }

    idToken, err := verifier.Verify(ctx, rawIDToken)
    if err != nil {
        http.Error(w, "Token verification failed: "+err.Error(), http.StatusInternalServerError)
        return
    }

    // Extract BIA-specific claims
    var claims struct {
        Sub               string   `json:"sub"`
        BioAssurance      string   `json:"bio_assurance_level"`
        BioLivenessActive bool     `json:"bio_liveness_active"`
        AMR               []string `json:"amr"`
    }
    if err := idToken.Claims(&claims); err != nil {
        http.Error(w, "Failed to parse claims: "+err.Error(), http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]interface{}{
        "message":       "Authenticated with biological identity",
        "bio_assurance": claims.BioAssurance,
        "liveness":      claims.BioLivenessActive,
        "amr":           claims.AMR,
    })
}

Step 5: Handle the Callback

When the user completes biological verification, BIA redirects back to your callback URL with an authorization code. Your server exchanges this code for tokens:

GET /callback?code=bia_authz_abc123&state=random-state-string

The token exchange returns three values:

Token	Purpose
`id_token`	Signed JWT with identity + bio claims. This is the core value of BIA.
`access_token`	Bearer token for the `/userinfo` endpoint
`refresh_token`	Long-lived token to refresh sessions (if `offline_access` scope requested)

Standard OIDC -- with biological proof

The callback flow is identical to any OIDC provider. The difference is what's inside the id_token: cryptographically-backed biological identity claims that no password-based system can provide.

Step 6: Use Bio Claims

Decode the id_token to access biological identity claims:

import jwt from "jsonwebtoken";

const decoded = jwt.decode(idToken, { complete: true });
const claims = decoded.payload;

// Check biological assurance level
if (claims.bio_assurance_level === "high") {
  // User verified with multiple biometric modalities
  grantFullAccess(claims.sub);
} else if (claims.bio_assurance_level === "substantial") {
  // User verified with at least one biometric modality + liveness
  grantStandardAccess(claims.sub);
} else {
  // Low assurance -- may want to prompt for step-up verification
  requestAdditionalVerification(claims.sub);
}

// Check specific biometric methods used
if (claims.amr.includes("bio:neuro")) {
  // EEG neural fingerprint was used -- highest uniqueness
  console.log("Neural identity confirmed");
}

if (claims.bio_liveness_active) {
  // Real-time liveness was verified (not a replay)
  console.log("Live biological presence confirmed");
}

Decision Matrix

Assurance Level	Modalities	Liveness	Use Case
`high`	2+ biometric	Active	Surgical consent, controlled substance prescriptions
`substantial`	1+ biometric	Active	Clinical trial enrollment, insurance claims
`low`	Genomic only	Passive	Patient portal access, appointment booking

What's in the `id_token`?

Here is a decoded BIA id_token showing all available claims:

{
  "header": {
    "alg": "ES256",
    "typ": "JWT",
    "kid": "bia-sig-2026-q1"
  },
  "payload": {
    // ── Standard OIDC Claims ──────────────────────────────
    "iss": "https://bia.ever.health",
    "sub": "bia_usr_8f3a1b2c4d5e6789",
    "aud": "bia_cid_a1b2c3d4e5f6",
    "exp": 1743609600,
    "iat": 1743606000,
    "auth_time": 1743605990,
    "nonce": "n-0S6_WzA2Mj",
    "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",

    // ── BIA Biological Identity Claims ────────────────────
    "bio_assurance_level": "high",
    "bio_liveness_active": true,
    "bio_liveness_timestamp": "2026-04-02T10:06:30Z",
    "bio_modalities_used": ["face", "fingerprint", "eeg"],
    "bio_commitment_hash": "0x7a8b...3f2e",
    "bio_genomic_verified": true,
    "bio_neuro_features": 15,
    "bio_neuro_confidence": 0.9987,
    "bio_match_score": 0.9995,

    // ── Health Vectors (when bio:neuro scope requested) ───
    "health_vectors": {
      "cognitive_load": "normal",
      "stress_index": "low",
      "sleep_quality": "good",
      "focus_stability": "high",
      "emotional_valence": "positive"
    },

    // ── Authentication Context ────────────────────────────
    "amr": ["bio:face", "bio:fingerprint", "bio:neuro", "bio:genomic"],
    "acr": "urn:bia:assurance:high",

    // ── ZK Proof Reference ────────────────────────────────
    "zk_proof_id": "zkp_9d8e7f6a5b4c",
    "zk_circuit_version": "bia-identity-v2",
    "zk_verified": true
  }
}

Claim Reference

Claim	Type	Description
`bio_assurance_level`	`string`	Overall assurance: `"high"`, `"substantial"`, or `"low"`
`bio_liveness_active`	`boolean`	Whether real-time liveness detection passed
`bio_liveness_timestamp`	`string`	ISO 8601 timestamp of the liveness check
`bio_modalities_used`	`string[]`	Biometric methods used: `"face"`, `"fingerprint"`, `"eeg"`
`bio_commitment_hash`	`string`	On-chain commitment hash for the identity
`bio_genomic_verified`	`boolean`	Whether genomic markers were verified
`bio_neuro_features`	`number`	Number of EEG features extracted (max 15)
`bio_neuro_confidence`	`number`	Neural fingerprint match confidence (0.0--1.0)
`bio_match_score`	`number`	Overall biometric match score (0.0--1.0)
`health_vectors`	`object`	Cognitive/health state from EEG (requires `bio:neuro` scope)
`amr`	`string[]`	Authentication methods: `"bio:face"`, `"bio:fingerprint"`, `"bio:neuro"`, `"bio:genomic"`
`acr`	`string`	Authentication context class reference
`zk_proof_id`	`string`	Reference ID for the zero-knowledge proof
`zk_circuit_version`	`string`	ZK circuit version used for verification
`zk_verified`	`boolean`	Whether the ZK proof was verified on-chain

Next Steps

You now have a working BIA integration. Here's where to go from here:

API Reference -- Complete endpoint documentation for the BIA OIDC Provider
Architecture Guide -- Deep dive into data flows, the ZK proof pipeline, and security model
ZK Proofs Guide -- Generate and verify zero-knowledge biological identity proofs
EEG Neural Fingerprint -- Understand the 15-feature neural identity model

Need help?

Join the Ever Developer Community or open an issue on GitHub. Our team monitors both channels.

Developer Quickstart

What You'll Build​

Prerequisites​

Step 1: Register Your Developer Account​

Step 2: Install the SDK​

Step 3: Configure OIDC​

Step 4: Add the Login Button​

Step 5: Handle the Callback​

Step 6: Use Bio Claims​

Decision Matrix​

What's in the id_token?​

Claim Reference​

Next Steps​