Back to Documentation
API Reference

API Reference

Complete documentation for the ECURTIY verification API. All endpoints use JSON.

Base URL

https://your-ecurtiy-domain.com

Use the ECURTIY cloud service URL for your API calls.

Authentication

Site Key (Public)

eck_live_...

Used in the widget, safe to expose in client-side code.

Secret Key (Private)

ecs_live_...

Used for server-side validation. Never expose publicly.

Verification Endpoints

POST
/api/challenge

Generate Challenge

Create a new Proof of Work challenge for the widget to solve.

Authentication

Site Key (Public)

Request Body

{
  "siteKey": "eck_live_your_site_key"
}

Response

{
  "challengeId": "ch_abc123...",
  "prefix": "random_prefix_string",
  "difficulty": 16,
  "expiresAt": "2024-12-08T12:05:00Z",
  "mode": "checkbox"
}

Notes

  • •Challenge expires after 5 minutes
  • •Difficulty ranges from 14-18 bits
  • •Mode is determined by site configuration
POST
/api/verify

Verify Solution

Submit the Proof of Work solution and behavioral data to get a verification token.

Authentication

None (Widget calls this)

Request Body

{
  "challengeId": "ch_abc123...",
  "nonce": 12345678,
  "solveTimeMs": 1850,
  "fingerprint": "sha256_hash_of_browser_data",
  "behavioral": {
    "mouseEntropy": 4.2,
    "interactionCount": 15,
    "sessionDuration": 3500
  }
}

Response

{
  "success": true,
  "token": "ect_verification_token...",
  "expiresAt": "2024-12-08T12:05:00Z"
}

Notes

  • •Token is valid for 5 minutes
  • •Token can only be used once
  • •Risk score must be below 0.7 to pass
POST
/api/validate

Validate Token

Server-side validation of a verification token. Call this from your backend.

Authentication

Secret Key (Private)

Request Body

{
  "token": "ect_verification_token...",
  "secretKey": "ecs_live_your_secret_key"
}

Response

{
  "success": true,
  "data": {
    "passed": true,
    "riskScore": 0.15,
    "solveTimeMs": 1850,
    "createdAt": "2024-12-08T12:00:00Z"
  }
}

Notes

  • •Always validate tokens server-side
  • •Tokens are marked as used after validation
  • •Returns detailed verification data

Site Management Endpoints

These endpoints require authentication via NextAuth session. Used by the dashboard.

GET
/api/sites

Get all sites for the authenticated user.

POST
/api/sites

Create a new site with generated API keys.

GET
/api/sites/[id]

Get details for a specific site.

PATCH
/api/sites/[id]

Update site settings (name, domain, mode, difficulty).

DELETE
/api/sites/[id]

Delete a site and all associated data.

POST
/api/sites/[id]/regenerate-keys

Generate new site key and secret key.

Analytics Endpoint

GET
/api/analytics/[siteId]

Get Site Analytics

Retrieve verification analytics for a specific site.

Query Parameters

period- One of: 24h, 7d, 30d, 90d

Response Fields

  • summary.totalVerifications - Total count in period
  • summary.passedVerifications - Successful verifications
  • summary.failedVerifications - Failed verifications
  • summary.passRate - Success percentage
  • summary.avgSolveTimeMs - Average solve time
  • summary.avgRiskScore - Average risk score
  • chartData - Daily breakdown array
  • recentVerifications - Last 10 verifications

Error Codes

INVALID_SITE_KEY

The provided site key is invalid or inactive

SITE_INACTIVE

The site has been deactivated

QUOTA_EXCEEDED

Monthly verification limit exceeded

CHALLENGE_EXPIRED

The challenge has expired (5 min TTL)

INVALID_SOLUTION

The PoW solution is incorrect

HIGH_RISK_SCORE

Risk score exceeded threshold (0.7)

TOKEN_EXPIRED

The verification token has expired

TOKEN_USED

The token has already been validated

INVALID_SECRET_KEY

The secret key is invalid

RATE_LIMITED

Too many requests, try again later

DocumentationWidget Guide