Veridex API

Trust surfaces, documented with restraint.

This documentation covers the public Veridex endpoints that are live today, plus the new embedded login contract for partner apps. It is intentionally narrow, deliberately calm, and written as a reference rather than a dashboard.

Trust response examples are sanitized to avoid publishing wallet addresses, evidence storage metadata, or raw platform exports. Embedded login remains additive and does not replace the existing first-party Veridex login.

Reading guide

Base URL

Replace <base-url> with the deployed API origin for your environment.

Authentication

Trust routes are public. Embedded login uses OAuth-style partner credentials and does not affect the normal Veridex app bearer token flow.

What is included

Embedded login, developer app setup, trust, reputation, reviews, and beta agent lookup. Broken or undocumented routes stay out of this contract.

Tone

These docs are the public contract for what external consumers should rely on right now.

Embedded Login

Authorize URL

GET /auth/authorize accepts client_id, redirect_uri, response_type=code, scope, state, code_challenge, code_challenge_method=S256, and optional response_mode=web_message|query.

Token exchange

POST /api/oauth/token is server-side only in v1 and expects grant_type, client_id, client_secret, code, redirect_uri, and code_verifier.

Identity payload

Tokens and GET /api/oauth/userinfo return identity-first fields: sub, veridex_user_id, and profile fields only when profile scope is granted.

Partner setup

Use the dedicated developer apps page to create partner apps. Each app gets a client_id, one-time client_secret, and a registered redirect URI allowlist.

Developer Apps

Need a client ID and secret?

Open the dedicated developer apps page to register a partner client and manage callback allowlists.

Open Developer Apps

Hosted SDK

Browser

<script src="<base-url>/veridex-auth.js"></script>
<script>
  async function loginWithVeridex() {
    const auth = await window.VeridexAuth.login({
      baseUrl: '<base-url>',
      clientId: 'vdx_cli_...',
      redirectUri: 'https://partner.example.com/auth/callback'
    });

    await fetch('/api/veridex/exchange', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(auth)
    });
  }
</script>

Backend

POST <base-url>/api/oauth/token
{
  "grant_type": "authorization_code",
  "client_id": "vdx_cli_...",
  "client_secret": "vdx_sec_...",
  "code": "<auth code>",
  "redirect_uri": "https://partner.example.com/auth/callback",
  "code_verifier": "<pkce verifier>"
}

GET

/api/trust/:veridexId

Resolve the public trust surface for a Veridex user, including Veridex score, score summaries, staking totals, and review aggregates.

Auth: None
Path params: 1 required
Response: JSON

Path parameters

Param	Description
`veridexId`	User UUID for the trust profile you want to read.

Success shape

veridex_id, display_name, is_verified_human, veridex_score, and overall_trust_score
score_summary for grouped scoring output and score_components for the current stored component map
total_staked, review_count, avg_rating, profession_category, skills, specializations, and years_experience

Common errors

404 with { "error": "User not found" } when the ID does not resolve
500 with { "error": "Query failed" } if the lookup fails server-side

Examples

Request

curl <base-url>/api/trust/<veridex-id>

Response

{
  "veridex_id": "user-uuid",
  "display_name": "Worker Name",
  "is_verified_human": true,
  "veridex_score": 40,
  "overall_trust_score": 40,
  "score_summary": {
    "evidence": 71,
    "employer": 60,
    "staking": 0,
    "veridex": 40
  },
  "score_components": {
    "identity_assurance": 90,
    "employer_outcomes": 60,
    "grouped_scores": {
      "evidence": 71,
      "employer": 60,
      "staking": 0,
      "veridex": 40
    }
  },
  "total_staked": 0,
  "review_count": 1,
  "avg_rating": 5,
  "profession_category": "software",
  "skills": ["Python", "Machine Learning"],
  "specializations": ["Machine Learning"],
  "years_experience": 7
}

The example above is sanitized and trimmed, but the field names match the live response shape.
Current production behavior sets is_verified_human to true for any resolved account returned by this route.

GET

/api/reputation/:userId

Return the public profile surface for a user, including the current worker profile payload, active reviews, and stake totals.

Auth: None
Path params: 1 required
Response: JSON

Path parameters

Param	Description
`userId`	User UUID for the profile you want to inspect.

Success shape

Top-level user, profile, reviews, totalStaked, and stakerCount keys
user contains the public user record minus nested worker profile data
profile contains the current stored worker profile object and may include additional computed fields when populated

Common errors

404 with { "error": "User not found" } when the ID does not resolve
500 with { "error": "Failed to get reputation" } if the profile lookup fails

Examples

Request

curl <base-url>/api/reputation/<user-id>

Response

{
  "user": {
    "id": "user-uuid",
    "display_name": "Worker Name",
    "roles": ["worker"],
    "profession_category": "software"
  },
  "profile": {
    "overall_trust_score": 40,
    "ingestion_status": "completed",
    "computed_skills": ["Python", "Machine Learning"],
    "score_components": {
      "grouped_scores": {
        "evidence": 71,
        "employer": 60,
        "staking": 0,
        "veridex": 40
      }
    }
  },
  "reviews": [
    {
      "id": "review-uuid",
      "rating": 5,
      "content": "Strong delivery on the engagement.",
      "job_category": "software",
      "stake_amount": 0,
      "reviewer_trust_score_at_time": 32,
      "status": "active",
      "reviewer": {
        "id": "reviewer-uuid",
        "display_name": "Hiring Manager",
        "roles": ["client"]
      }
    }
  ],
  "totalStaked": 0,
  "stakerCount": 0
}

This route currently returns a broader profile payload than the trust endpoint and is the best public source for review and stake context.
Examples are intentionally trimmed and do not expose stored wallet or evidence metadata.

GET

/api/review/:workerId

List active public reviews for a worker in stake order, with reviewer display metadata attached.

Auth: None
Path params: 1 required
Response: JSON

Path parameters

Param	Description
`workerId`	User UUID for the worker whose active reviews you want to read.

Success shape

A single top-level reviews array
Each review entry includes review metadata, scoring context, contract linkage when present, and a nested reviewer object
Returns 200 with an empty reviews array when there are no active reviews

Common errors

500 with { "error": "Failed to get reviews" } if the query fails

Examples

Request

curl <base-url>/api/review/<worker-id>

Response

{
  "reviews": [
    {
      "id": "review-uuid",
      "reviewer_id": "reviewer-uuid",
      "worker_id": "worker-uuid",
      "rating": 5,
      "content": "Strong delivery on the engagement.",
      "job_category": "software",
      "stake_amount": 0,
      "reviewer_trust_score_at_time": 32,
      "is_flagged": false,
      "flag_reason": null,
      "status": "active",
      "created_at": "2026-04-05T02:43:39.167026+00:00",
      "contract_id": "contract-uuid",
      "reviewer": {
        "id": "reviewer-uuid",
        "display_name": "Hiring Manager"
      }
    }
  ]
}

This route is narrower than /api/reputation/:userId and is the cleanest feed for standalone review ingestion.

GETBeta

/api/agent/:agentId

Resolve an agent credential back to its parent human, including the delegated score snapshot, domain restrictions, and public verification status.

Auth: None
Path params: 1 required
Response: JSON

Path parameters

Param	Description
`agentId`	Agent credential UUID.

Success shape

Top-level is_verified plus nested agent and parent objects
agent includes identifier metadata, inheritance_fraction, authorized_domains, stake_amount, penalty state, and timestamps
parent includes the current effective trust score plus the underlying base score and active agent penalty total

Common errors

404 with { "error": "Agent not found", "is_verified": false } when the credential does not exist
500 with { "error": "Lookup failed" } if the lookup fails server-side

Examples

Request

curl <base-url>/api/agent/<agent-id>

Response

{
  "is_verified": true,
  "agent": {
    "id": "agent-uuid",
    "name": "Shopping Agent",
    "identifier": "https://demo-agent.app",
    "identifier_type": "api_endpoint",
    "deployment_surface": "api",
    "agent_score": 100,
    "derived_score": 59,
    "current_penalty_points": 0,
    "max_penalty_points": 59,
    "inheritance_fraction": 0.7,
    "authorized_domains": ["payments", "negotiation"],
    "stake_amount": 0.5,
    "status": "active",
    "dispute_count": 0,
    "created_at": "2026-04-05T01:23:45.000Z"
  },
  "parent": {
    "display_name": "Verified Human",
    "base_overall_trust_score": 85,
    "agent_penalty_score": 0,
    "trust_score": 85
  }
}

The live route already returns the beta verification shape above; the example is sanitized, but the field names match production.
Use this route for counterparty checks before letting an agent act on a user’s behalf.

Notes

GET /api/reputation/browse/workers is intentionally excluded from the public contract. It currently exists as an app-oriented browse feed rather than a stable external integration surface, so it stays undocumented even though the route is live.

The product-facing route for this page is /api-docs. Use/query-demo for the live explorer that exercises these public endpoints from inside the app, and /developers/apps for the standalone embedded-login app management experience.