← DocumentationGuide

Ownership Verification

Prove you control your agents using OAuth, callback challenge, or embed verification. Three methods, choose the one that fits your setup.

Why Verify Ownership

Registering an agent proves you claim it. Ownership verification proves you control it. This distinction matters — verified agents receive higher trust from platforms, which translates to better rate limits and access tiers.

The verification status on your agent moves from unverified → pending → verified.

Method 1: OAuth Verification

Best for agents that run on a platform with OAuth support (e.g., GitHub, Slack). ASN authenticates you with the platform and matches your identity to the agent's external ID.

1. Start verification: POST /agents/:asn/verify/start with {"method": "oauth"}
2. ASN returns an OAuth redirect URL
3. You authenticate with the platform
4. ASN matches your platform identity to the agent's external_id
5. If they match, ownership is verified
POST /api/v1/agents/ASN-2026-0384-0001-7/verify/start
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json

{
  "method": "oauth",
  "platform_id": "platform-uuid"
}

// Response
{
  "verification_id": "ver-uuid-...",
  "method": "oauth",
  "status": "pending",
  "oauth_url": "https://platform.example/oauth/authorize?..."
}

Method 2: Callback Challenge

Best for agents you have runtime control over. ASN issues a challenge token. Your agent must respond to a callback URL with the token, proving you have code-level control.

1. Start verification with {"method": "callback"}
2. ASN returns a challenge token (64-char random string)
3. Configure your agent to respond at the callback URL
4. ASN calls your agent's callback endpoint
5. If the token matches, ownership is verified
POST /api/v1/agents/ASN-2026-0384-0001-7/verify/start
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json

{
  "method": "callback"
}

// Response
{
  "verification_id": "ver-uuid-...",
  "method": "callback",
  "status": "pending",
  "challenge_token": "a1b2c3d4e5f6...64chars",
  "challenge_expires_at": "2026-03-19T12:00:00Z",
  "callback_url": "https://asn.earth/api/v1/agents/ASN-2026-0384-0001-7/verify/callback"
}

Your agent must POST the challenge token to the callback URL before it expires:

POST /api/v1/agents/ASN-2026-0384-0001-7/verify/callback
Content-Type: application/json

{
  "challenge_token": "a1b2c3d4e5f6...64chars"
}

Method 3: Embed Verification

Best for agents with a public profile page, documentation site, or README. Place a verification token in a publicly accessible location and ASN crawls it.

1. Start verification with {"method": "embed"}
2. ASN returns a verification token
3. Place the token at the specified location (HTML meta tag, JSON file, or README)
4. ASN crawls the location and checks for the token
5. If found and valid, ownership is verified
// Example: place in your agent's documentation
<meta name="asn-verify" content="a1b2c3d4e5f6...64chars" />

// Or in a .well-known file:
// https://your-agent.dev/.well-known/asn-verify.json
{
  "asn": "ASN-2026-0384-0001-7",
  "token": "a1b2c3d4e5f6...64chars"
}

Verification Expiry

Challenge tokens expire if not completed within the window (typically 24 hours). If a verification attempt expires, start a new one. There is no limit on attempts.

Once verified, the status persists unless the agent is deactivated or the operator account is suspended.

← DocumentationKYC Verification →