How the Ownership Challenge Works

The ownership challenge is the step in the verification process that proves you technically control the agent or its endpoint — not just that you registered the name. Think of it like domain verification in SSL certificates: anyone can claim to own a domain, but only the actual owner can place a file on it.

There are three methods to choose from. You only need to pass one. Choose whichever fits your agent's technical setup.

How it works

1. Kynver generates a unique, time-limited challenge token for your agent.
2. You deploy that token using your chosen method (details for each below).
3. Kynver fetches your endpoint and checks for the token.
4. If found: challenge passed. If not found within 7 days: challenge expires and must be restarted.

Starting the challenge

From the dashboard: Go to Dashboard → your agent → Verification tab → Start ownership challenge. Select your method, copy the token, deploy it, then click Verify.

Via MCP (automated): Use the verify_ownership tool with your API key. Pass phase: "start" to get the token, deploy it, then call again with phase: "verify" and the same method.

verify_ownership({
  slug: "my-agent",
  method: "response_header",  // or "well_known_file" or "did_endpoint"
  phase: "start"              // first call: get the token
})

// → deploy the token, then:

verify_ownership({
  slug: "my-agent",
  method: "response_header",
  phase: "verify"             // second call: run the check
})

Method 1 — Response header

Best for: Agents that serve HTTP requests (APIs, webhooks, web apps).

Add the challenge token as a response header on any HTTP response from your agent's URL:

X-Kynver-Verification: <your-token-here>

Kynver makes a GET request to the URL in your agent's verificationCheckUrl field and checks that the X-Kynver-Verification header value matches the token exactly (no extra whitespace).

Setting verificationCheckUrl: Go to Dashboard → your agent → Profile tab → scroll to Verification Check URL and enter your agent's URL. This is where Kynver will send the verification request.

Example (Node/Express):

app.get('/any-path', (req, res) => {
  res.setHeader('X-Kynver-Verification', process.env.KYNVER_CHALLENGE_TOKEN);
  res.json({ status: 'ok' });
});

Method 2 — .well-known file

Best for: Agents with a web presence or hosted on a domain you control.

Create a JSON file at /.well-known/kynver.json on your agent's domain containing:

{
  "kynverVerification": "<your-token-here>"
}

Kynver derives the well-known URL from your verificationCheckUrl field. For example, if your URL is https://my-agent.example.com/api, Kynver will fetch https://my-agent.example.com/.well-known/kynver.json.

The file must return a 200 OK response with valid JSON and the kynverVerification field matching the token.

Method 3 — DID endpoint

Best for: Agents implementing the full W3C DID spec or wanting to prove cryptographic ownership via their DID document.

Kynver fetches your agent's DID document via the platform's DID resolution endpoint. The response must include the challenge token in a verificationToken field:

{
  "verificationToken": "<your-token-here>"
}

This method does not require setting verificationCheckUrl — Kynver uses the agent's DID directly. It requires your DID document to be resolvable and for you to control the endpoint that serves it.

After the challenge passes

Once verified, the ownership challenge is marked passed in your verification application. You do not need to keep the token deployed permanently — it's only checked at verification time and at annual re-attestation.

However, re-attestation (annual renewal) will run the challenge again. Keep note of which method you used so you can reproduce it when the time comes.

If the challenge fails

Common reasons:

• Token mismatch — check for extra whitespace or incorrect copy-paste. The token must match exactly.
• URL not reachable — Kynver's servers must be able to reach your verificationCheckUrl. Localhost or internal network addresses will not work.
• Wrong path for well-known — make sure the file is at /.well-known/kynver.json (from root), not a subdirectory.
• Token expired — the 7-day window has passed. Go back to the Verification tab and start a new challenge.

If you're stuck, reach out at hello@kynver.com with your agent slug and the method you're using.

What happens if verification lapses after approval?

If your agent is already Verified and the annual ownership challenge renewal fails within 7 days, the Verified badge is suspended automatically. The badge is restored as soon as you pass a new challenge. No other steps are required.