Publisher Integration

For publishers who want to handle their own billing processes, Adlocaite provides a validation system that verifies advertiser invoicing keys through your custom endpoints.

Invoicing Key Validation

When an advertiser provides an invoicing key for billing through your system, Adlocaite will validate this key by calling your custom validation endpoint. This ensures that only valid advertisers can use your billing system.

Endpoint Requirements

Publishers must provide a custom HTTP endpoint that:

1. Accepts POST requests for key validation
2. Implements Bearer token authentication using your provided token
3. Includes rate limiting to prevent abuse
4. Monitors for suspicious activities and implements appropriate security measures
5. Returns structured JSON responses indicating key validity

Authentication

All validation requests from Adlocaite will include your Bearer token in the Authorization header:

Authorization: Bearer YOUR_PUBLISHER_TOKEN

Request Format

Adlocaite will send a POST request to your validation endpoint with the following body:

{
  "invoicing_key": "advertiser_billing_key_123"
}

Response Format

Your endpoint must return a 200 OK status with one of the following response formats:

Valid Key Response

{
  "key_valid": true,
  "expiry": 1735689600
}

Invalid Key Response

{
  "key_valid": false
}

The expiry field is optional and should contain a Unix timestamp indicating when the key expires.

Example Implementation

Here's how Adlocaite will call your validation endpoint:

curl -X POST https://your-domain.com/api/validate-key \
  -H "Authorization: Bearer YOUR_PUBLISHER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoicing_key": "advertiser_billing_key_123"
  }'

Expected responses:

For valid keys:

{
  "key_valid": true,
  "expiry": 1735689600
}

For invalid keys:

{
  "key_valid": false
}

Validation Schedule

Adlocaite performs key validation in the following scenarios:

1. Initial Setup: When an advertiser first provides an invoicing key
2. Key Updates: Whenever an advertiser updates their invoicing key
3. Periodic Checks: Regular validation to ensure keys remain active
4. Before Billing: Prior to processing any billing transactions

Security Requirements

Your validation endpoint must implement:

Rate Limiting

• Maximum of 100 requests per minute per IP
• Implement exponential backoff for repeated failures
• Return 429 Too Many Requests when limits are exceeded

Suspicious Activity Monitoring

• Log all validation attempts with timestamps and IP addresses
• Monitor for patterns indicating abuse or automated attacks
• Implement temporary blocking for suspicious IPs
• Alert your security team for unusual validation patterns

Error Handling

• Return appropriate HTTP status codes
• Provide clear error messages for debugging
• Implement proper timeout handling (max 30 seconds)

Testing Your Integration

Before going live, test your validation endpoint with these scenarios:

1. Valid Key Test: Confirm valid keys return key_valid: true
2. Invalid Key Test: Confirm invalid keys return key_valid: false
3. Expired Key Test: Test keys with past expiry timestamps
4. Rate Limit Test: Verify rate limiting is working correctly
5. Authentication Test: Confirm requests without valid Bearer tokens are rejected
6. Timeout Test: Ensure your endpoint responds within 30 seconds

Support

If you need assistance implementing your validation endpoint, contact our integration team at support@adlocaite.com with:

• Your publisher ID
• Proposed validation endpoint URL
• Bearer token for authentication
• Expected go-live timeline

Response times:

• Priority: Within 4 hours for critical integration issues
• Standard: Within 24 hours for general questions