Skip to main content

ID PASS DataCollect Backend API

REST API for the ID PASS DataCollect backend server. The server is the central sync hub for offline-first DataCollect clients (mobile, web, admin UI) and coordinates external integrations via the adapter registry.

Authentication​

Most endpoints require a JWT access token in the Authorization header:

Authorization: Bearer <token>

Access tokens are issued by POST /api/users/login and expire after one hour. Use POST /api/users/refresh to get a new access token (and rotated refresh token) without re-prompting for credentials — field agents use this to stay signed in while offline. Self-service endpoints (/api/auth/**) issue separate scoped tokens via OTP, national ID, or OIDC exchange.

Multi-tenant (multi-program) support​

All tenant-scoped endpoints accept a configId query parameter (or field in the request body). Each configuration has its own entity forms, entity data, auth providers, and external-sync settings. Non-admin users can only access configurations listed in their tenantIds claim — the validateTenantAccess middleware enforces this on every tenant-scoped route.

Synchronization​

The sync endpoints support bidirectional synchronization between clients and server, as well as external system integration. Internal sync uses cursor-based pagination (nextCursor is a composite timestamp|eventGuid) to prevent event skipping. External sync push runs as a background job with progress updates persisted to sync_events.

Version: 2.0.0

API Information​

  • Base URL: http://localhost:3000
  • Authentication: Bearer JWT tokens
  • Content Type: application/json

Quick Start​

1. Authentication​

Most endpoints require JWT authentication. Get a token by logging in:

curl -X POST http://localhost:3000/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@hdm.example",
    "password": "your-password"
  }'

2. Using the Token​

Include the token in subsequent requests:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3000/api/users/me

API Endpoints​

This API provides the following endpoint categories:

  • 0 - Health checks and server metadata
  • 1 - User login, token refresh, and current-user lookup
  • 2 - Admin-only user CRUD and role assignment
  • 3 - Multi-tenant program configuration (entity forms, adapters, auth)
  • 4 - Query entities (groups, individuals, records) and their events
  • 5 - Pull and push events between clients and the sync server
  • 6 - Background jobs that synchronize with external systems (OpenSPP, OpenFn, Mock)
  • 7 - Upload, download, list, and delete binary attachments linked to entities
  • 8 - Citizen-facing authentication (OTP, national ID, OIDC) and change requests
  • 9 - Review and resolve entities flagged as potential duplicates
  • 10 - Discover field metadata from OpenSPP V1 (Odoo) and V2 (REST) registries

OpenAPI Specification​

  • Download: openapi.yaml
  • JSON Endpoint: openapi.json (when server is running)
  • Import into tools: Postman, Insomnia, or any OpenAPI-compatible client

This documentation is automatically generated from the OpenAPI specification.