Developer Docs

LYNK API v1.0

Physical presence verification API with usage-based per-scan billing.

Version

1.0.0

Status

Live

Billing Unit

Per Scan

Pricing assumptions: published onboarding and per-scan rates are standard monthly terms and may be reduced for annual commitments and higher contracted volume.

Endpoints

GET /api/v1 — API metadata and endpoint discovery

GET /api/v1/health — service health check

POST /api/v1/verify — submit a verification scan request

GET /api/v1/usage — usage aggregation for billing/reporting

GET /api/v1/openapi — OpenAPI 3.1 JSON schema

API Schema

Machine-readable OpenAPI specification for request/response contracts and integration tooling.

Open OpenAPI JSON

Canonical Verification Flow

The product flow is intentionally fixed: onboarding verification first, wallet pass provisioning, then runtime backend decisioning from NFC tap events.

1) User signs up and completes identity checks (plus optional screening).

2) User provisions Lynk Verified in Apple Wallet or Google Wallet.

3) Provider initiates verification session and prompts wallet-open NFC tap.

4) In rideshare, both rider and driver must be verification-ready for bilateral protection.

5) Backend evaluates policy/context and returns allow/deny result.

6) Green check is shown only when backend verification passes.

Internal source-of-truth doc: docs/verification-flow.md.

Commercial Model

Default model is B2B2C: platform-side accounts pay for onboarding and runtime verification, while verifier-side users (for example riders or homeowners) verify at no charge.

1) Onboarding uses high-assurance ID verification (document + selfie/liveness).

2) Rideshare can require both rider and driver onboarding verification while keeping rider UX free.

3) Runtime uses fast, per-scan policy checks tied to wallet/NFC session context.

4) Background checks are packaged as a separate optional add-on.

Internal source-of-truth doc: docs/billing-model.md.

Wallet Rollout

1) Google Wallet can be enabled now through wallet API routes.

2) Apple Wallet endpoint is reserved as coming soon.

3) Trust cards should only be issued after verification approval.

Internal source-of-truth doc: docs/wallet-setup.md.

Authentication

Send your API key in the Authorization header:

Authorization: Bearer <your_api_key>

Set LYNK_API_V1_KEY for one key, or LYNK_API_V1_KEYS as a comma-separated list for multiple clients.

Rate Limiting

Requests are limited per API key in a fixed time window.

Env: LYNK_API_V1_RATE_LIMIT (default: 120)

Env: LYNK_API_V1_RATE_WINDOW_SECONDS (default: 60)

Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Verify Scan Example

curl -X POST https://your-domain.com/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{
    "endpointId": "rides-driver-v1",
    "referenceId": "trip_12345",
    "subjectId": "driver_abc",
    "signals": {
      "nfcTap": true,
      "deviceMatch": true,
      "biometricMatch": true,
      "gpsDistanceMeters": 12
    }
  }'

Response includes verification decision, risk score, reason codes, and billable scan quantity.

Event Persistence

Verification events are written to Firestore collection api_verifications when Firebase project env vars are configured.

Usage API Example

Query scan usage with optional from, to, or days params.

curl -X GET "https://your-domain.com/api/v1/usage?days=30" \
  -H "Authorization: Bearer <your_api_key>"

Response includes total scans, approved/denied counts, daily usage, endpoint breakdown, and risk-level distribution.

Need higher volume?

Use custom scan-rate contracts and SLA support on Enterprise plans.

View Pricing