Partner API · v1

Verify, link & endorse — anywhere.

Drop EthicCred verified identity + endorsements into any site in under 10 minutes. One signed REST surface, plus a zero-config JavaScript widget.

HMAC-signed
SHA-256 over timestamp + body, 5-minute replay window.
Drop-in widget
One script tag renders search, create and endorsement states.
Webhooks
Phase 2 — push updates when scores or endorsements change.

1 · Quickstart

  1. Ask EthicCred to provision a partner record (name, slug, allowed domains, scopes).
  2. Receive your client_id and client_secret (shown once).
  3. Compute an HMAC signature on every request (snippet below) and start calling the API.
  4. Optionally embed the widget to render the identity card on your profile pages.

2 · Authentication

Every request must include three headers:

X-EC-Client-Id: ec_live_...
X-EC-Timestamp: <unix-seconds>
X-EC-Signature: hex(HMAC-SHA256(secret, timestamp + "\\n" + body))
# Node — compute the HMAC and call lookup
const crypto = require("crypto");
const body = JSON.stringify({ email: "jane@example.com" });
const ts   = String(Math.floor(Date.now() / 1000));
const sig  = crypto.createHmac("sha256", CLIENT_SECRET)
                   .update(ts + "\n" + body).digest("hex");
await fetch("https://ethiccred.com/api/partner/v1/users/lookup", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-EC-Client-Id": CLIENT_ID,
    "X-EC-Timestamp": ts,
    "X-EC-Signature": sig,
  },
  body,
});

3 · Drop-in Widget

Paste this where you render each user's profile card. The widget auto-detects whether the user has a passport and shows the correct state.

<!-- EthicCred drop-in widget -->
<div id="ethiccred-widget"
     data-partner-id="YOUR_CLIENT_ID"
     data-user-email="${user.email}"
     data-user-ref="${user.id}"
     data-accent="#059669"></div>
<script src="https://ethiccred.com/widget.js" async></script>

4 · Endpoints

POST/api/partner/v1/users/lookupscope · verify

Look up an EthicCred passport by email, phone, or EthicCred ID.

Request body
{
  "email": "jane@example.com"
}
Response
{
  "found": true,
  "user": {
    "ethiccred_id": "EC-7F4K-9LX2",
    "display_name": "Jane Doe",
    "trust_score": 92,
    "tier": "Trusted"
  }
}
POST/api/partner/v1/usersscope · create

Create a new EthicCred passport from a partner session (name + email).

Request body
{
  "full_name": "Jane Doe",
  "email": "jane@example.com",
  "partner_user_ref": "coyoin-user-9211"
}
Response
{
  "created": true,
  "ethiccred_id": "EC-7F4K-9LX2",
  "magic_setup_url": "/setup-account?token=..."
}
POST/api/partner/v1/linksscope · verify

Link an existing EthicCred ID to one of your users for persistent display.

Request body
{
  "partner_user_ref": "coyoin-user-9211",
  "ethiccred_id": "EC-7F4K-9LX2"
}
Response
{ "ok": true, "link_id": "..." }
POST/api/partner/v1/endorsementsscope · endorse

Submit an endorsement that lands in the user's EthicCred inbox for Accept/Reject.

Request body
{
  "ethiccred_id": "EC-7F4K-9LX2",
  "role": "Freelance Developer",
  "company": "CoyoIN",
  "start_date": "2025-01-01",
  "end_date": "2025-06-30",
  "rating": 5,
  "feedback": "Delivered on time, excellent communication.",
  "employer_name": "Bob Hirer",
  "employer_email": "bob@coyoin.com"
}
Response
{ "ok": true, "endorsement_id": "...", "status": "pending" }
GET/api/partner/v1/users/{id}/publicscope · verify

Fetch the public passport summary for a known EthicCred ID.

Response
{
  "ethiccred_id": "EC-7F4K-9LX2",
  "display_name": "Jane Doe",
  "trust_score": 92,
  "tier": "Trusted"
}

5 · Webhooks (Phase 2)

Register a webhook_url on your partner record to receive signed events: user.linked, user.created, endorsement.accepted, endorsement.rejected, trust_score.updated.