IPQS
Login Register
<< Back to Categories
Authentication
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.

  1. The user clicks a button or link on your website similar to the link found under the "Authenticating" section below.

  2. The user is asked to log in or register with IPQS. The user then logs in.

  3. 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.

  4. 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.

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.

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.

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
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.

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)

Ready to eliminate fraud?

Start fighting fraud now with 5,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618

Schedule a Demo Sign Up