- About the IPQS APIs
- Proxy & VPN Detection API
- Email Verification API
- Phone Number Validation API
- Malicious URL Scanner API
- Device Fingerprint API
- Mobile Device Fingerprinting SDK
- Gaming Fraud Detection SDK
- Dark Web Leak API
- Malware File Scanner API
- Request List API
- Fraud Reporting API
- Account Management APIs
- Bulk Validation CSV
- Allowlist Blocklist APIs
- Plugins Platforms Integrations
- IP Reputation Database
- IP Address Abuse Feed
- Email Verification Database
-
Custom Integrations
- Getting Started
- Authentication
- Refresh Secret
- IP & Proxy Checks
- Email Verification Checks
- Phone Number Validity Checks
- Device Tracker
- List Device Trackers
- Device Tracker Statistics
- Login Tokens
- Overview Statistics
- Recent Proxy Statistics
- Recent Email Statistics
- Fraud Reporting
- Retrieve Requests by ID
- Country List API Documentation
- Release Notes
About Authenticating Custom Integrations
To make queries on behalf of your users, you must have them authenticate with IPQS. Authentication can be as simple as sending them to a URL on our site (via link or iframe) and storing the key they return once logged in.
Note
Using our integration system requires us to set up a special landing page on our site for you. We refer to this landing page as the "login URL" elsewhere in the documentation. Contact the IPQS support team to get your unique login URL.
Flow
Below is the order in which users should end up authenticating with IPQS.
- The user clicks a button or link on your website similar to the link found under the "Authenticating" section below.
- The user is asked to log in or register with IPQS. The user then logs in.
- Once the user has successfully logged in to IPQS, they are presented with the option to integrate with your site. They choose to accept, thereby confirming their interest in the integration.
- The user is returned to your site with a "secret" for their account. You then store this secret for future use. Each user has a unique secret.
Authenticating
Below is an example of an authentication URL. Depending on your use case, your parameters may be different, or you may not need any parameters at all.
In the example above, the user will be redirected back to https://example.com/ipq/finish.
Authentication Parameters
| Parameter | Description | Example Value |
|---|---|---|
| domain | The domain the user will be sent back to. If this parameter is not specified the user will be sent back to the referring domain. | |
| success_path | The path on your domain the user will be sent back to upon successful login. This is the path that should capture the user's unique secret. This parameter must be URL encoded. Do not include GET parameters in this path. | /integration/finish |
| failure_path | The path on your domain the user will be sent back to on failure to login. This parameter must be URL encoded. | /integration/failure |
| path | A fallback path in the event your success/failure paths are not passed or you wish for success and failure to end up at the same path. This parameter must be URL encoded. | /integration/submit |
| protocol | The protocol the user will be sent back to on success/failure. Possible values: http or https. Failure to provide this parameter will default to the referring url's protocol. |
domain fields
Note
This parameter is used in future API calls as the "key". Be sure to store this information somewhere as it is required to make API calls.
example.com
protocol fields
Note
https is strongly encouraged.
https
Additional GET parameters passed to this API end point will be returned to the success URL. Do not put them in success_path or append them to your domain. Our system will automatically forward them to you.
Warning
You can not name your custom parameters: email, password, domain, success_path, failure_path, path, protocol , secret, access_token, status, or state. Our system will ignore or strip them.
Return and Secret
When the user returns to your success path, they will return with the GET parameters listed below:
Note
You are highly encouraged to call refresh after receiving your secret API key to ensure that you have a unique API secret, even if your user's browsing history is compromised.
| Parameter | Description | Format |
|---|---|---|
| secret, access_token and code | The authentication secret used by future API requests for the user in question. | char(128) |
| status | The status of the request: "auth_success" or "auth_failure" | varchar(64) |
| state | Optional pass through parameter to allow for CSRF prevention. | varchar(64) |