Proxy Detection Service

Core API Service: /get & /getToken

The fundamental way to use the Proxy Detection Service is by making a GET request to its endpoints. The /get endpoint returns full JSON details, while /getToken (and /getToken.json) provide just the token.

GET https://proxy-detection.cname.cloud/get
GET https://proxy-detection.cname.cloud/getToken
GET https://proxy-detection.cname.cloud/getToken.json

Request (for all Core API endpoints)

You can customize the token's expiration time with a query parameter:

Response (from /get)

On success, the /get service returns a JSON object containing all detection data and the JWT token:

{
  "ip": "203.0.113.42",
  "asn": 15169,
  "companyName": "GOOGLE",
  "ipType": "Hosting",
  "isProxy": false,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." 
}
      

JWT Payload

The decoded JWT (token field value) will contain claims providing insights. Always verify the JWT's signature on your backend.

Example decoded payload with enhanced detection:

{
  "ip": "203.0.113.42",      // Client's IP Address
  "asn": 15169,              // Autonomous System Number
  "companyName": "GOOGLE",   // ASN Organization name
  "ipType": "Hosting",       // IP Type classification (Residential, VPN, Hosting, etc.)
  "isProxy": false,          // Boolean or null: true if proxy/VPN/Tor, false if not, null if uncertain
  "iat": 1678886400,         // Issued At timestamp
  "exp": 1678886700          // Expiration timestamp
}
      

Token-Only Endpoints

The /getToken endpoint returns only the JWT token as plain text. The /getToken.json endpoint returns the JWT token in a JSON wrapper: {"token": "YOUR_JWT"}.

GET https://proxy-detection.cname.cloud/getToken?ttl=600
Content-Type: text/plain
Response: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET https://proxy-detection.cname.cloud/getToken.json?ttl=600
Content-Type: application/json
Response: {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

Benefits of Direct API Usage

• Universal Applicability: Use from any environment that can make HTTP requests.
• Full Control: Manage token fetching, storage, and injection precisely.
• Server-Side Enrichment: Your backend can call this API for incoming requests.

Client-Side Helper: load.js

How It Works

• Synchronous Instantiation: Create an instance of the ProxyDetection helper immediately. No token is fetched at this stage.
• On-Demand Token Fetching: Call the instance.getToken() method to get a token. This method returns a Promise that resolves with the token string (or null).
  • It first checks its internal cache (memory, then localStorage).
  • If no valid, non-expired token is found (or if TTL preferences changed), it fetches a new one from the API.
• Optional AJAX Interception: If configured with patchGlobalAjax: true, it can still intercept fetch and XMLHttpRequest to replace a URL placeholder (e.g., {PROXY_TOKEN}) with a token obtained via getToken(). By default, this is false.

Usage

1. Include the Script: Ensure load.js is available in your project.

   <script src="https://proxy-detection.cname.cloud/load.js" defer></script>

2. Instantiate and Configure: In your JavaScript, create an instance of ProxyDetection, passing configuration options.

   // Example: In your main application script
   document.addEventListener('DOMContentLoaded', () => {
     const pdInstance = ProxyDetection({
       tokenRequestTtlSeconds: 600, // Request 10-minute tokens
       logConsoleMethod: 'info',    // 'none', 'log', 'info', 'debug'
       verboseLogging: false,
       patchGlobalAjax: false       // Default, explicitly shown
       // tokenEndpointBase: 'https://your-custom-proxy.com/get' // Optional: if self-hosting
     });
   
     // Now you can use pdInstance.getToken() when needed
   });

3. Get and Use Tokens: Call pdInstance.getToken() when you need a token. This returns a Promise.

   // Example: Fetching a token to include in a header
   async function makeApiCallWithToken() {
     if (!window.pdInstance) { // Assuming pdInstance is made available globally or via module
       console.error("ProxyDetection instance not ready.");
       return;
     }
     try {
       const token = await pdInstance.getToken();
       if (token) {
         const response = await fetch('/api/some-data', {
           headers: {
             'X-Proxy-Token': token // Or your preferred header name
           }
         });
         const data = await response.json();
         console.log("Data with token:", data);
       } else {
         console.warn("No proxy token obtained. Making call without it or handling error.");
         // Potentially make the call without the token or show an error
       }
     } catch (error) {
       console.error("Error getting proxy token or making API call:", error);
     }
   }
   

4. Manual AJAX Injection (if patchGlobalAjax: false): You are responsible for integrating the token into your requests. This is common when using libraries like HTMX or having fine-grained control.

   // Example with HTMX (see full HTMX example below)
   // In an HTMX event like htmx:configRequest:
   // e.detail.headers['YOUR-TOKEN-HEADER-NAME'] = await pdInstance.getToken(); 
   

5. Using Automatic AJAX Patching (if patchGlobalAjax: true): If you enable automatic patching, load.js will attempt to replace a placeholder in your URLs.
   1. Set patchGlobalAjax: true during instantiation.
   2. Add your chosen placeholder (default: {PROXY_TOKEN}) to URLs in your AJAX calls or relevant HTML attributes that might trigger network requests via JavaScript (e.g., if a script dynamically sets an image src).

      // If patchGlobalAjax: true
      // fetch('/api/data?param=value&securityToken={PROXY_TOKEN}'); 
      // The {PROXY_TOKEN} will be replaced.
      // The placeholder string can be configured via options.placeholderQueryPart.
      

Configuration Options (Passed as an Object)

Configure ProxyDetection by passing an options object during instantiation:

const pd = ProxyDetection({ /* your options here */ });

Example Instantiation with Options:

const proxyDetect = ProxyDetection({
  tokenRequestTtlSeconds: 900,      // Request 15-minute tokens
  logConsoleMethod: 'info',         // Show informational logs
  patchGlobalAjax: true,            // Enable automatic URL token replacement
  placeholderQueryPart: '{MY_TOKEN}'  // Use a custom placeholder
});

// Later, when you need it:
// proxyDetect.getToken().then(token => { /* ... */ });

// Or if patchGlobalAjax is true:
// fetch('/some/api?key={MY_TOKEN}');
      

The load.js library provides more control, clearly separating instantiation from token acquisition, and making automatic AJAX patching an explicit choice.