Custom Integrations - Authentication Documentation
In order to make queries on your user's behalf you must have them authenticate with IPQualityScore. This can be as simple as sending them to a URL on our site (via link or iframe) and then storing the key they return with once they've finished logging in.
Using our integration system requires us to setup a special landing page for you on our site. We refer to this landing page as the "base URL" elsewhere in the documentation. If you have not done so already please contact the IPQualityScore support team by clicking here to get your base URL.
Flow
Below is the order in which users should end up authenticating with IPQualityScore.
- User clicks a button or link on your website similar to the link found under the "Authenticating" section below.
- User is asked to login or register with IPQualityScore. (They login or register.)
- User has logged in to IPQualityScore, they are asked to confirm if they would like to integrate with your site. (They accept.)
- User is sent back 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 what an authentication url should look like. Your parameters may be different or you may not need any parameters at all dependant on your use case. Be sure to replace ExampleIntegration with your integration.
https://www.ipqualityscore.com/oauth/ExampleIntegration/login?domain=example.com&success_path=%2Fipq%2Ffinish
In the example above the user will be redirected back to https://example.com/ipq/finish
Possible Parameters| Parameter | Description | Example Value |
|---|---|---|
| domain | The domain the user will be sent back to. (Note: If this parameter is not specified the user will be sent back to the referring domain.) 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. | google.com |
| 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. (Note: 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. (Note: 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. (Note: 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. 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 on to your domain. Our system will automatically forward them to you. Notice: You can not name your custom parameters: email, password, domain, success_path, failure_path, path, protocol, secret, access_token, status or state. They will be ignored or stripped by our system.
Return and Secret
When the user returns to your success path they should return with the GET parameters listed below.
| Parameter | Description | Description |
|---|---|---|
| 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) |
It is strongly encouraged that you call refresh after receiving your secret API key to ensure that even if your user's browsing history is compromised you have a unique API secret.