Developers

API Reference

Full REST API documentation for the Evodira merchant trust platform.

Base URL

# All requests
https://api.evodira.com/api/v1/{endpoint}

# Example
POST https://api.evodira.com/api/v1/auth/login

The prefix /api/v1 is required on every request. All responses are JSON. Timestamps are ISO-8601 UTC. IDs are UUIDs.

Authentication

Operator sessions (cookie-based): Call POST /auth/login with email and password. The server sets two HTTP-only cookies:

  • lmt_access — short-lived JWT used for all authenticated requests
  • lmt_refresh — long-lived token; call POST /auth/refresh to rotate

Platform API (key-based): Include your API key as an HTTP header on every request:

X-API-Key: <your-platform-api-key>

Platform API keys are managed by a platform_admin in the operator console under Settings → API Keys. Keys are scoped to the platform_api role and cannot call operator-only endpoints (e.g. review decisions, user management).

Inspector sessions: Field inspectors authenticate through the partner app with a separate phone + API key flow. Inspector sessions use lmt_insp_access andlmt_insp_refresh cookies and cannot access internal operator endpoints.

Roles & Permissions

Every protected endpoint requires a specific permission string. A user's effective permissions are determined by their role. Admins can also grant individual permission overrides via PUT /auth/users/{user_id}.

RoleWho uses itPermissions included
platform_adminFull access to all features and settings.All permissions
qc_leadQC leadership — review, appeals, corrective actions, tasks, evidence, risk, intelligence, verification.merchant.read/update/suspend, review.*, appeal.*, corrective_action.*, evidence.*, complaint.read, risk.read, intelligence.read, verification.*, task.*, audit.read, settings.read
qc_reviewerStandard QC analyst — review and corrective actions without high-impact decisions.merchant.read/update, review.read/decide, appeal.*, corrective_action.*, evidence.*, complaint.read, risk.read, intelligence.read
viewerRead-only access to merchants, evidence, complaints, and risk scores.merchant.read, review.read, evidence.read, complaint.read, risk.read, intelligence.read, trigger.read
inspectorField inspector — uses partner app, separate cookie auth.task.read/create/complete, evidence.upload
platform_apiMachine-to-machine — uses X-API-Key header.merchant.create/read, evidence.upload, complaint.ingest, webhook.manage/read, settings.manage

Endpoints

AuthenticationSession-based authentication via HTTP-only cookies. Supports TOTP 2FA, session listing/revocation, and password flows.▲
POST/auth/loginAuthenticate with email + password. Sets lmt_access & lmt_refresh HTTP-only cookies.
Request Body
email (string, required)password (string, required)
If TOTP is enabled, returns requires_2fa: true and sets a 5-minute 2FA challenge cookie. Complete with POST /auth/login/2fa.
POST/auth/login/2faComplete 2FA login using a TOTP code.
Request Body
code (string, 6 digits)
POST/auth/refreshExchange lmt_refresh cookie for a new lmt_access token.
POST/auth/logoutRevoke the current session and clear cookies.🔒 auth
GET/auth/meReturn the currently authenticated user with permissions[].🔒 auth
PUT/auth/meUpdate own profile (name, email).🔒 auth
Request Body
full_name (optional string)email (optional string)
GET/auth/sessionsList all active sessions for the current user.🔒 auth
DELETE/auth/sessions/{session_id}Revoke a specific session by ID.🔒 auth
DELETE/auth/sessions/allRevoke all active sessions (except current).🔒 auth
GET/auth/usersList all platform users.🔒 authuser.read
Query Params
skip (int, default 0)limit (int, default 25)
POST/auth/usersCreate a new user.🔒 authuser.manage
Request Body
emailfull_namerole (platform_admin | qc_lead | qc_reviewer | viewer)permissions[] (optional override)
GET/auth/users/{user_id}Get user details.🔒 authuser.read
PUT/auth/users/{user_id}Update user (role, permissions, active state).🔒 authuser.manage
DELETE/auth/users/{user_id}Deactivate a user account.🔒 authuser.manage
POST/auth/2fa/setupGenerate TOTP secret and QR code data URI.🔒 auth
POST/auth/2fa/verifyEnable TOTP using the setup code. Returns recovery_codes[].🔒 auth
POST/auth/2fa/disableDisable TOTP for the current user.🔒 auth
GET/auth/2fa/statusReturn { enabled: bool } for the current user.🔒 auth
POST/auth/password/changeChange own password (requires current_password).🔒 auth
POST/auth/password/forgotInitiate password reset email (unauthenticated).
Request Body
email (string, required)
POST/auth/password/resetComplete reset with token from email.
Request Body
token (string)new_password (string)
MerchantsCreate and manage merchant records. Each merchant has owners[], locations[], and a live trust status.▼
EvidenceSubmit and retrieve visual evidence assets. Each asset is run through the AI pipeline for quality, scene, and risk assessment.▼
ComplaintsIngest and query consumer complaints. Each complaint is auto-classified by category, severity, intent, and extracted symptoms.▼
RiskRisk score computation, trigger evaluation, score history, and configurable trigger policies. Internal scores expose 9 component dimensions.▼
Review CasesTwo-tier manual review workflow. A reviewer makes an initial decision; high-impact decisions require a second approval.▼
Corrective ActionsStructured remediation workflow: CREATE → SUBMIT_FIX → APPROVE/REJECT → COMPLETE. Merchants submit evidence of fixes; reviewers approve.▼
Platform IntegrationMachine-to-machine API for platform partners. Uses X-API-Key header. Covers merchant onboarding, evidence submission, complaint ingestion, webhook management, and order/refund event streaming.▼
Public TrustUnauthenticated endpoints for embeddable badges and public merchant status. Cached for 5 minutes. Never exposes raw scores.▼
IntelligenceExternal signals, reputation artifacts, and AI-generated recommendations for merchant improvement.▼
OperationsMerchant appeals against trust decisions. Two-step: create an appeal, then review it.▼

Risk Score Components

The internal risk score is composed of 9 independently weighted components. Each is a float from 0–1 (higher = more risk). The aggregate internal_score is a weighted mean.

ComponentWhat it measures
identity_confidenceConfidence that the owner's identity is verifiable and consistent
location_confidenceGPS accuracy, claimed vs. observed location match, geofence compliance
evidence_integrityQuality and authenticity of submitted visual evidence assets
visible_operational_riskObservable operational issues found in evidence (hygiene, signage, etc.)
complaint_riskVolume, severity, and recency of consumer complaints
fulfilment_reliabilityOrder fulfilment rate, refund frequency, and cancellation patterns
reputation_integrityExternal signals: social reviews, news mentions, reputation artifacts
external_signal_riskThird-party data signals (regulatory, financial, partner flags)
behavioural_anomaly_riskUnusual patterns in operational behaviour or submission cadence

Pagination

List endpoints accept skip and limit query parameters. Responses wrap items in a standard envelope:

{
  "items": [...],
  "total": 142,
  "skip": 0,
  "limit": 25
}

Error Codes

StatusMeaning
400Bad Request — malformed JSON or invalid query parameter
401Unauthorized — missing or expired lmt_access cookie, or invalid X-API-Key
403Forbidden — authenticated but your role/permissions don't include the required permission
404Not Found — resource UUID does not exist or belongs to a different tenant
409Conflict — state machine violation (e.g. completing an already-completed action) or duplicate external ID
422Validation Error — request body failed field validation (see detail[] array for field paths)
429Rate Limit Exceeded — back off and retry after X-RateLimit-Reset
500Internal Server Error — check /status for active incidents
// 422 Validation Error envelope
{
  "detail": [
    { "loc": ["body", "email"], "msg": "value is not a valid email address", "type": "value_error" },
    { "loc": ["body", "claimed_address"], "msg": "field required", "type": "missing" }
  ]
}

See Also

Webhooks → — push-based event delivery for risk status changes, review decisions, and trigger firings.

Trust Badges → — embed live merchant trust badges with a single HTML snippet.