API Reference

Complete REST API documentation for the BIA OIDC Provider. All endpoints are served from https://bia.ever.health.

Base URL

Production: https://bia.ever.health Sandbox: https://sandbox.bia.ever.health

All requests must use HTTPS. HTTP requests are rejected with 301 Moved Permanently.

Authentication

API endpoints use two authentication schemes:

Scheme	Used By	Format
Bearer Token (Developer API Key)	Developer Platform endpoints	Authorization: Bearer bia_dev_ak_...
Client Credentials	Token endpoint (confidential clients)	HTTP Basic or client_id + client_secret in body

---

Standard OIDC Endpoints

Discovery

GET /.well-known/openid-configuration

Returns the OpenID Connect discovery document. Use this to auto-configure your OIDC client.

Authentication: None

Response:

{
  "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",
  "registration_endpoint": "https://bia.ever.health/bio-oidc/register",
  "jwks_uri": "https://bia.ever.health/.well-known/jwks.json",
  "scopes_supported": [
    "openid", "bio", "bio:liveness", "bio:neuro", "bio:genomic", "offline_access"
  ],
  "response_types_supported": ["code", "id_token", "code id_token"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["pairwise"],
  "id_token_signing_alg_values_supported": ["ES256", "RS256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic", "client_secret_post", "private_key_jwt"
  ],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat", "auth_time", "nonce",
    "bio_assurance_level", "bio_liveness_active", "bio_liveness_timestamp",
    "bio_modalities_used", "bio_commitment_hash", "bio_genomic_verified",
    "bio_neuro_features", "bio_neuro_confidence", "bio_match_score",
    "health_vectors", "amr", "acr", "zk_proof_id", "zk_verified"
  ],
  "acr_values_supported": [
    "urn:bia:assurance:low",
    "urn:bia:assurance:substantial",
    "urn:bia:assurance:high"
  ]
}

Example:

curl https://bia.ever.health/.well-known/openid-configuration

---

Authorization

GET /bio-oidc/authorize

Initiates the BIA authentication flow. Redirects the user to the biological verification interface.

Authentication: None (browser redirect)

Query Parameters:

Parameter	Type	Required	Description
client_id	string	Yes	Your application's client ID
redirect_uri	string	Yes	URL to redirect after authentication. Must match a registered URI.
response_type	string	Yes	Must be code for authorization code flow
scope	string	Yes	Space-separated scopes. Must include openid.
state	string	Yes	Opaque value for CSRF protection
nonce	string	Yes	Random value bound to the id_token
acr_values	string	No	Requested assurance level: urn:bia:assurance:high, urn:bia:assurance:substantial, urn:bia:assurance:low
bio_modalities	string	No	Comma-separated requested modalities: face, fingerprint, eeg
prompt	string	No	login forces re-authentication. consent forces consent screen.
max_age	number	No	Maximum authentication age in seconds
code_challenge	string	No	PKCE code challenge (required for public clients)
code_challenge_method	string	No	Must be S256 when using PKCE

Scopes:

Scope	Claims Returned
openid	sub, iss, aud, exp, iat, auth_time
bio	bio_assurance_level, bio_modalities_used, bio_match_score, amr, acr
bio:liveness	bio_liveness_active, bio_liveness_timestamp
bio:neuro	bio_neuro_features, bio_neuro_confidence, health_vectors
bio:genomic	bio_genomic_verified, bio_commitment_hash
offline_access	Returns a refresh_token

Example:

# Construct the authorization URL and redirect the user
https://bia.ever.health/bio-oidc/authorize?\
  client_id=bia_cid_a1b2c3d4e5f6&\
  redirect_uri=https://localhost:3000/callback&\
  response_type=code&\
  scope=openid%20bio%20bio:liveness&\
  state=af0ifjsldkj&\
  nonce=n-0S6_WzA2Mj&\
  acr_values=urn:bia:assurance:substantial

Success Response: Redirects to redirect_uri with code and state parameters.

Error Response: Redirects to redirect_uri with error and error_description parameters.

Error	Description
invalid_request	Missing or invalid parameter
unauthorized_client	Client not authorized for this grant type
access_denied	User denied consent or biometric verification failed
unsupported_response_type	Response type not supported
invalid_scope	Requested scope is invalid or unknown
bio_verification_failed	Biometric verification did not meet the requested assurance level
bio_liveness_failed	Liveness detection failed

---

Token

POST /bio-oidc/token

Exchanges an authorization code for tokens, or refreshes an existing session.

Authentication: Client credentials (HTTP Basic or body params)

Content-Type: application/x-www-form-urlencoded

Request Body (Authorization Code):

Parameter	Type	Required	Description
grant_type	string	Yes	authorization_code
code	string	Yes	The authorization code from the callback
redirect_uri	string	Yes	Must match the URI used in the authorize request
client_id	string	Yes	Your client ID (if not using HTTP Basic auth)
client_secret	string	Yes	Your client secret (if not using HTTP Basic auth)
code_verifier	string	Conditional	PKCE code verifier (required if code_challenge was sent)

Request Body (Refresh Token):

Parameter	Type	Required	Description
grant_type	string	Yes	refresh_token
refresh_token	string	Yes	The refresh token
scope	string	No	Reduced scope for the new token

Success Response (200):

{
  "access_token": "bia_at_eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFUzI1NiIs...",
  "refresh_token": "bia_rt_dGhpcyBpcyBh..."
}

Error Responses:

Status	Error	Description
400	invalid_grant	Code is expired, already used, or invalid
400	invalid_client	Client authentication failed
400	unsupported_grant_type	Grant type not supported
401	invalid_client	Invalid client credentials

Example:

curl -X POST https://bia.ever.health/bio-oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "bia_cid_a1b2c3d4e5f6:bia_cs_..." \
  -d "grant_type=authorization_code" \
  -d "code=bia_authz_abc123" \
  -d "redirect_uri=https://localhost:3000/callback"

---

UserInfo

GET /bio-oidc/userinfo

Returns claims about the authenticated user. The claims returned depend on the scopes granted during authorization.

Authentication: Bearer token (access_token)

Response (200):

{
  "sub": "bia_usr_8f3a1b2c4d5e6789",
  "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": {
    "cognitive_load": "normal",
    "stress_index": "low",
    "sleep_quality": "good",
    "focus_stability": "high",
    "emotional_valence": "positive"
  },
  "amr": ["bio:face", "bio:fingerprint", "bio:neuro", "bio:genomic"],
  "acr": "urn:bia:assurance:high"
}

Error Responses:

Status	Error	Description
401	invalid_token	Access token is expired or invalid
403	insufficient_scope	Token lacks the required scope for requested claims

Example:

curl https://bia.ever.health/bio-oidc/userinfo \
  -H "Authorization: Bearer bia_at_eyJhbGciOi..."

---

Dynamic Client Registration

POST /bio-oidc/register

Dynamically register a new OIDC client. Follows RFC 7591.

Authentication: None (open registration) or Bearer token (authenticated registration)

Request Body:

{
  "redirect_uris": ["https://app.example.com/callback"],
  "client_name": "My Health App",
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "openid bio bio:liveness",
  "contacts": ["dev@example.com"],
  "logo_uri": "https://app.example.com/logo.png",
  "policy_uri": "https://app.example.com/privacy",
  "tos_uri": "https://app.example.com/terms"
}

Response (201):

{
  "client_id": "bia_cid_x9y8z7w6v5u4",
  "client_secret": "bia_cs_...",
  "client_id_issued_at": 1743606000,
  "client_secret_expires_at": 0,
  "redirect_uris": ["https://app.example.com/callback"],
  "client_name": "My Health App",
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "openid bio bio:liveness"
}

Error Responses:

Status	Error	Description
400	invalid_redirect_uri	Redirect URI is not HTTPS or is malformed
400	invalid_client_metadata	Required metadata is missing or invalid

Example:

curl -X POST https://bia.ever.health/bio-oidc/register \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["https://app.example.com/callback"],
    "client_name": "My Health App",
    "grant_types": ["authorization_code"],
    "response_types": ["code"],
    "scope": "openid bio"
  }'

---

BIA Extension Endpoints

Wallet Response

POST /bio-oidc/wallet-response

Receives a verifiable presentation from a wallet during the on-chain authentication flow. Used when the user authenticates via a blockchain wallet that holds BIA credentials.

Authentication: None (called by wallet)

Request Body:

{
  "vp_token": "eyJhbGciOi...",
  "presentation_submission": {
    "id": "ps_1a2b3c",
    "definition_id": "bia_identity_request",
    "descriptor_map": [
      {
        "id": "bio_identity_credential",
        "format": "jwt_vp",
        "path": "$.vp_token",
        "path_nested": {
          "id": "bio_identity_credential",
          "format": "jwt_vc",
          "path": "$.vp.verifiableCredential[0]"
        }
      }
    ]
  },
  "state": "af0ifjsldkj"
}

Response (200):

{
  "redirect_uri": "https://app.example.com/callback?code=bia_authz_abc123&state=af0ifjsldkj",
  "session_id": "sess_4d5e6f7g",
  "bio_assurance_level": "high",
  "verified": true
}

Error Responses:

Status	Error	Description
400	invalid_presentation	VP token is malformed or signature is invalid
400	credential_expired	Verifiable credential has expired
403	verification_failed	Biometric verification in the credential did not pass
404	session_not_found	The state does not match any active authorization session

Example:

curl -X POST https://bia.ever.health/bio-oidc/wallet-response \
  -H "Content-Type: application/json" \
  -d '{
    "vp_token": "eyJhbGciOi...",
    "presentation_submission": {
      "id": "ps_1a2b3c",
      "definition_id": "bia_identity_request",
      "descriptor_map": [{
        "id": "bio_identity_credential",
        "format": "jwt_vp",
        "path": "$.vp_token"
      }]
    },
    "state": "af0ifjsldkj"
  }'

---

Commitment

POST /bio-oidc/commitment

Creates or updates a biological identity commitment. A commitment is a cryptographic binding between a user's biometric template and their on-chain identity, without revealing the underlying biometric data.

Authentication: Bearer token (access_token with bio:genomic scope)

Request Body:

{
  "commitment_type": "genomic",
  "commitment_hash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a",
  "proof": {
    "circuit_id": "bia-genomic-commitment-v2",
    "proof_data": "base64-encoded-zk-proof...",
    "public_inputs": [
      "0x7a8b9c0d...",
      "0x1a2b3c4d..."
    ]
  },
  "metadata": {
    "marker_count": 44,
    "reference_build": "GRCh38",
    "extraction_method": "vcf_v4.3"
  }
}

Response (201):

{
  "commitment_id": "cmt_5a6b7c8d9e",
  "commitment_hash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a",
  "status": "verified",
  "on_chain_tx": "0xabcdef1234567890...",
  "block_number": 18456789,
  "created_at": "2026-04-02T10:15:00Z",
  "expires_at": "2027-04-02T10:15:00Z"
}

Error Responses:

Status	Error	Description
400	invalid_commitment	Commitment hash format is invalid
400	proof_verification_failed	ZK proof did not verify against the commitment
401	invalid_token	Access token is missing or invalid
403	insufficient_scope	Token lacks bio:genomic scope
409	commitment_exists	A commitment for this identity already exists. Use PUT to update.

Example:

curl -X POST https://bia.ever.health/bio-oidc/commitment \
  -H "Authorization: Bearer bia_at_eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "commitment_type": "genomic",
    "commitment_hash": "0x7a8b9c0d...",
    "proof": {
      "circuit_id": "bia-genomic-commitment-v2",
      "proof_data": "base64-encoded-zk-proof...",
      "public_inputs": ["0x7a8b9c0d...", "0x1a2b3c4d..."]
    }
  }'

---

Developer Platform Endpoints

All developer platform endpoints require a developer API key.

Register Developer

POST /bio-oidc/developers/register

Create a new developer account on the BIA platform.

Authentication: None

Request Body:

{
  "email": "dev@yourcompany.com",
  "password": "your-secure-password",
  "organization": "Your Company",
  "website": "https://yourcompany.com",
  "use_case": "Healthcare patient verification"
}

Response (201):

{
  "developer_id": "dev_8f3a1b2c4d5e",
  "email": "dev@yourcompany.com",
  "organization": "Your Company",
  "api_key": "bia_dev_ak_...",
  "status": "active",
  "created_at": "2026-04-02T10:00:00Z",
  "rate_limits": {
    "requests_per_minute": 60,
    "apps_allowed": 10
  }
}

Error Responses:

Status	Error	Description
400	invalid_email	Email format is invalid
400	weak_password	Password does not meet complexity requirements
409	email_taken	A developer account with this email already exists

Example:

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

---

Create Application

POST /bio-oidc/developers/apps

Register a new application under your developer account.

Authentication: Bearer token (Developer API Key)

Request Body:

{
  "name": "My Health App",
  "description": "Patient identity verification for telehealth",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "bio_assurance_required": "substantial",
  "bio_modalities": ["face", "fingerprint"],
  "token_endpoint_auth_method": "client_secret_basic",
  "logo_uri": "https://app.example.com/logo.png"
}

Field	Type	Required	Description
name	string	Yes	Application display name (3--64 characters)
description	string	No	Short description of the application
redirect_uris	string[]	Yes	Allowed redirect URIs (must be HTTPS, except localhost)
grant_types	string[]	Yes	authorization_code, refresh_token
response_types	string[]	No	Defaults to ["code"]
bio_assurance_required	string	No	Minimum assurance: high, substantial, low. Default: low
bio_modalities	string[]	No	Required modalities: face, fingerprint, eeg
token_endpoint_auth_method	string	No	client_secret_basic, client_secret_post, private_key_jwt
logo_uri	string	No	Logo URL displayed during consent

Response (201):

{
  "app_id": "app_7x9k2m4n",
  "client_id": "bia_cid_a1b2c3d4e5f6",
  "client_secret": "bia_cs_...",
  "name": "My Health App",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://localhost:3000/callback"
  ],
  "bio_assurance_required": "substantial",
  "bio_modalities": ["face", "fingerprint"],
  "status": "active",
  "created_at": "2026-04-02T10:00:00Z"
}

Error Responses:

Status	Error	Description
400	invalid_redirect_uri	Redirect URI is not HTTPS or is malformed
400	invalid_name	Name is too short, too long, or contains invalid characters
400	invalid_modality	Unrecognized biometric modality
401	unauthorized	Invalid or missing API key
409	name_taken	An app with this name already exists under your account
429	app_limit_reached	Maximum number of apps for your plan reached

Example:

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"
  }'

---

List Applications

GET /bio-oidc/developers/apps

List all applications under your developer account.

Authentication: Bearer token (Developer API Key)

Query Parameters:

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20, max: 100)
status	string	No	Filter by status: active, suspended, pending

Response (200):

{
  "apps": [
    {
      "app_id": "app_7x9k2m4n",
      "client_id": "bia_cid_a1b2c3d4e5f6",
      "name": "My Health App",
      "status": "active",
      "bio_assurance_required": "substantial",
      "created_at": "2026-04-02T10:00:00Z",
      "last_auth_at": "2026-04-02T14:30:00Z",
      "total_authentications": 1247
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

Example:

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

---

Get Application

GET /bio-oidc/developers/apps/:appId

Retrieve details for a specific application.

Authentication: Bearer token (Developer API Key)

Path Parameters:

Parameter	Type	Description
appId	string	The application ID

Response (200):

{
  "app_id": "app_7x9k2m4n",
  "client_id": "bia_cid_a1b2c3d4e5f6",
  "name": "My Health App",
  "description": "Patient identity verification for telehealth",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "bio_assurance_required": "substantial",
  "bio_modalities": ["face", "fingerprint"],
  "token_endpoint_auth_method": "client_secret_basic",
  "logo_uri": "https://app.example.com/logo.png",
  "status": "active",
  "created_at": "2026-04-02T10:00:00Z",
  "updated_at": "2026-04-02T10:00:00Z",
  "total_authentications": 1247,
  "last_auth_at": "2026-04-02T14:30:00Z"
}

Error Responses:

Status	Error	Description
401	unauthorized	Invalid or missing API key
404	app_not_found	Application not found or does not belong to your account

Example:

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

---

Update Application

PUT /bio-oidc/developers/apps/:appId

Update an existing application's configuration.

Authentication: Bearer token (Developer API Key)

Path Parameters:

Parameter	Type	Description
appId	string	The application ID

Request Body: Same fields as Create Application. Only include fields you want to change.

{
  "name": "My Health App v2",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://app.example.com/callback/v2"
  ],
  "bio_assurance_required": "high",
  "bio_modalities": ["face", "fingerprint", "eeg"]
}

Response (200):

{
  "app_id": "app_7x9k2m4n",
  "client_id": "bia_cid_a1b2c3d4e5f6",
  "name": "My Health App v2",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://app.example.com/callback/v2"
  ],
  "bio_assurance_required": "high",
  "bio_modalities": ["face", "fingerprint", "eeg"],
  "status": "active",
  "updated_at": "2026-04-02T11:00:00Z"
}

Error Responses:

Status	Error	Description
400	invalid_redirect_uri	Redirect URI is not HTTPS or is malformed
401	unauthorized	Invalid or missing API key
404	app_not_found	Application not found

Example:

curl -X PUT https://bia.ever.health/bio-oidc/developers/apps/app_7x9k2m4n \
  -H "Authorization: Bearer bia_dev_ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bio_assurance_required": "high",
    "bio_modalities": ["face", "fingerprint", "eeg"]
  }'

---

Delete Application

DELETE /bio-oidc/developers/apps/:appId

Permanently delete an application. This revokes all issued tokens and invalidates the client credentials.

Authentication: Bearer token (Developer API Key)

Path Parameters:

Parameter	Type	Description
appId	string	The application ID

Response (200):

{
  "app_id": "app_7x9k2m4n",
  "status": "deleted",
  "deleted_at": "2026-04-02T12:00:00Z",
  "tokens_revoked": 42
}

Error Responses:

Status	Error	Description
401	unauthorized	Invalid or missing API key
404	app_not_found	Application not found

Irreversible action

Deleting an application immediately revokes all access tokens, refresh tokens, and client credentials. Users currently authenticated through this application will be signed out. This action cannot be undone.

Example:

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

---

Get SDK Configuration

GET /bio-oidc/developers/apps/:appId/sdk-config

Returns a ready-to-use SDK configuration object for your application.

Authentication: Bearer token (Developer API Key)

Path Parameters:

Parameter	Type	Description
appId	string	The application ID

Response (200):

{
  "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",
  "client_id": "bia_cid_a1b2c3d4e5f6",
  "scopes_supported": ["openid", "bio", "bio:liveness", "bio:neuro", "bio:genomic"],
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://localhost:3000/callback"
  ],
  "bio_assurance_required": "substantial",
  "bio_modalities": ["face", "fingerprint"]
}

Example:

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

---

Get API Documentation

GET /bio-oidc/developers/docs

Returns the machine-readable OpenAPI 3.1 specification for the BIA API.

Authentication: Bearer token (Developer API Key)

Query Parameters:

Parameter	Type	Required	Description
format	string	No	json (default) or yaml

Response (200): OpenAPI 3.1 specification document.

Example:

curl https://bia.ever.health/bio-oidc/developers/docs?format=yaml \
  -H "Authorization: Bearer bia_dev_ak_..."

---

Test Authentication

POST /bio-oidc/developers/apps/:appId/test-auth

Trigger a test authentication flow in the sandbox environment. Returns a simulated id_token with configurable bio claims -- no real biometric hardware needed.

Authentication: Bearer token (Developer API Key)

Path Parameters:

Parameter	Type	Description
appId	string	The application ID

Request Body:

{
  "bio_assurance_level": "high",
  "bio_modalities": ["face", "fingerprint", "eeg"],
  "bio_liveness_active": true,
  "bio_genomic_verified": true,
  "bio_neuro_confidence": 0.9987,
  "simulate_failure": false
}

Field	Type	Required	Description
bio_assurance_level	string	No	Simulated assurance level. Default: app's configured minimum
bio_modalities	string[]	No	Simulated modalities used
bio_liveness_active	boolean	No	Simulate liveness pass/fail. Default: true
bio_genomic_verified	boolean	No	Simulate genomic verification. Default: true
bio_neuro_confidence	number	No	Simulated neural confidence (0.0--1.0). Default: 0.99
simulate_failure	boolean	No	If true, returns an authentication failure response

Response (200):

{
  "test": true,
  "id_token": "eyJhbGciOiJFUzI1NiIs...",
  "access_token": "bia_test_at_...",
  "decoded_claims": {
    "sub": "bia_test_usr_000000",
    "bio_assurance_level": "high",
    "bio_liveness_active": true,
    "bio_modalities_used": ["face", "fingerprint", "eeg"],
    "amr": ["bio:face", "bio:fingerprint", "bio:neuro"]
  },
  "expires_in": 3600
}

Sandbox only

Test authentication is only available for sandbox applications. Production applications must use real biometric flows.

Example:

curl -X POST https://bia.ever.health/bio-oidc/developers/apps/app_7x9k2m4n/test-auth \
  -H "Authorization: Bearer bia_dev_ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bio_assurance_level": "high",
    "bio_modalities": ["face", "fingerprint", "eeg"],
    "simulate_failure": false
  }'

---

Developer Statistics

GET /bio-oidc/developers/stats

Returns aggregate statistics across all your applications.

Authentication: Bearer token (Developer API Key)

Query Parameters:

Parameter	Type	Required	Description
period	string	No	day, week, month (default), year
app_id	string	No	Filter to a specific application

Response (200):

{
  "period": "month",
  "start_date": "2026-03-02T00:00:00Z",
  "end_date": "2026-04-02T00:00:00Z",
  "total_authentications": 12847,
  "successful_authentications": 12103,
  "failed_authentications": 744,
  "unique_users": 3891,
  "assurance_breakdown": {
    "high": 4521,
    "substantial": 6832,
    "low": 750
  },
  "modality_usage": {
    "face": 11200,
    "fingerprint": 8900,
    "eeg": 4521,
    "genomic": 2100
  },
  "average_verification_time_ms": 2340,
  "daily_breakdown": [
    {
      "date": "2026-04-01",
      "authentications": 456,
      "success_rate": 0.94
    }
  ]
}

Example:

curl "https://bia.ever.health/bio-oidc/developers/stats?period=week" \
  -H "Authorization: Bearer bia_dev_ak_..."

---

Error Format

All error responses follow a consistent format:

{
  "error": "error_code",
  "error_description": "Human-readable description of the error",
  "error_uri": "https://docs.ever.health/errors/error_code",
  "request_id": "req_a1b2c3d4e5"
}

Include the request_id when contacting support for faster debugging.

Rate Limits

Plan	Requests/minute	Apps	Monthly Authentications
Free	60	3	1,000
Developer	300	10	50,000
Enterprise	3,000	Unlimited	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1743606060

When rate limited, the API returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "error_description": "Rate limit exceeded. Try again in 23 seconds.",
  "retry_after": 23
}

Pagination

List endpoints return paginated results:

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "total_pages": 8
  }
}

Use ?page=2&limit=50 to navigate through results.