Kobaru
  1. Transparent Proxy
Kobaru
  • Kobaru.io Gateway API
    • Introduction
      • What is Kobaru?
      • Quick start
      • How x402 works
    • Integration
      • Standard x402 SDK
      • Advanced SDK
      • Transparent proxy integration
      • Direct API integration
    • Core Concepts
      • Available Chains and Assets
      • Payment schemes
      • Security
      • Usage models
    • Guides
      • Pricing your API
      • Going to Production
      • Testing with devnet
      • Bazaar discovery
    • API Reference
      • Error Handling
      • Get Supported Payment Kinds
      • Verify Payment Authorization
      • Settle Payment
    • Discovery
      • List Discovery Resources
    • Transparent Proxy
      • Overview - Transparent Proxy
      • Upstream authentication
      • Troubleshooting
      • Constraints and security
      • Capabilities and routes
      • Domain verification
      • Service setup
    • Schemas
      • SupportedResponse
      • ErrorResponse
      • UnauthorizedResponse
      • RateLimitResponse
      • VerifySuccessResponse
      • VerifyErrorResponse
      • SettleSuccessResponse
      • SettleErrorResponse
      • DiscoveryResourceItem
      • ListDiscoveryResourcesResponse
  1. Transparent Proxy

Domain verification

Before creating a proxy service, you need to prove you own the domain your API runs on. This prevents unauthorized proxying of third-party APIs.

Why verification is required#

Domain verification ensures that only you can create a proxy service pointing to your API. Without it, anyone could proxy traffic to your endpoints and charge for access.
When you verify a domain, you gain authorization for:
The exact domain (e.g., api.example.com)
All subdomains (e.g., v2.api.example.com)

Verification methods#

DNS TXT record (recommended)#

Best for apex domains and subdomains where you control DNS settings.
How to set it up:
1.
Go to Proxy > Domains in the Kobaru Console
2.
Click Add Domain and enter your domain
3.
Select DNS TXT as the verification method
4.
Add the following DNS record at your DNS provider:
Record Type: TXT
Hostname:    _kobaru-verify.yourdomain.com
Value:       kobaru-verify=abc123def456...
TTL:         3600 (or auto)
5.
Click Verify Now in the Console
Verify it's working:
You should see the kobaru-verify=... value in the response.

HTTP file verification#

Best when you don't have DNS access but can upload files to your web server.
How to set it up:
1.
Go to Proxy > Domains in the Kobaru Console
2.
Click Add Domain and enter your domain
3.
Select HTTP File as the verification method
4.
Create the verification file on your server:
5.
Make sure the file is accessible at:
https://yourdomain.com/.well-known/kobaru-verify.txt
6.
Click Verify Now in the Console
Verify it's working:

Verification token lifecycle#

Generated as a cryptographically secure random token (256 bits)
Expires after 7 days
Stored as a hash in the database (never in plaintext)
Renewable by deleting the expired domain and re-adding it
IMPORTANT: Do NOT remove the DNS record or verification file after successful verification. We continuously monitor domain ownership, and removing the verification will cause your proxy service to go down.

Managing domains#

The domain management page at Proxy > Domains shows:
ColumnDescription
DomainThe domain name
CoverageShows the *.domain.com wildcard pattern
MethodDNS TXT or HTTP File
StatusPending, Verified, Failed, or Expired
Verified atTimestamp of successful verification
From this page you can:
View verification instructions for pending domains
Retry verification if the first attempt failed
Delete domains you no longer need

Common issues#

DNS verification keeps failing#

1.
Check DNS propagation: dig TXT _kobaru-verify.yourdomain.com
2.
Make sure there are no trailing dots in the hostname
3.
Wait for your DNS TTL to expire (use a lower TTL like 300 during setup)
4.
Verify the value matches exactly (some DNS providers add quotes automatically)
5.
For apex domains, some providers require @ as the hostname

HTTP file verification fails#

1.
Ensure the file is accessible: curl https://yourdomain.com/.well-known/kobaru-verify.txt
2.
Confirm HTTPS is enabled (HTTP will fail)
3.
Check there are no redirects (301/302 can cause issues)
4.
Verify file permissions (should be readable)
5.
Make sure no authentication is required for the .well-known path

Token expired#

Verification tokens expire after 7 days. Delete the domain in the Console and add it again to get a new token.

Next steps#

Once your domain is verified, create a proxy service to start routing traffic.
Modified at 2026-02-10 21:52:35
Previous
Capabilities and routes
Next
Service setup
Built with