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. You can view a demo of this flow at our sample integration by clicking here.

  1. User clicks a button or link on your website similar to the link found under the "Authenticating" section below.
  2. User is asked to login or register with IPQualityScore. (They login or register.)
  3. User has logged in to IPQualityScore, they are asked to confirm if they would like to integrate with your site. (They accept.)
  4. 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://ipqualityscore.com/oauth/ExampleIntegration/login?domain=integration.ipqualityscore.com&success_path=%2Fipq%2Ffinish


In the example above the user will be redirected back to https://integration.ipqualityscore.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.) /ipqualityscore/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.) /ipqualityscore/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.) /ipqualityscore/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

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.