API

Article author
Minetta Gould
  • Updated

We have a REST API which can be accessed whilst on trial or through a professional subscription to DNSFilter. The documentation for the API can be found at the link below:

Documentation: API Documentation

API: API Link

Temporary Token

The following parameters can be used when acquiring a temporary token:

client_id: zJ1WJHavuUFx89cConwlipxoOc2J3TVQ
realm: Username-Password-Authentication
audience: https://dnsfilter.auth0.com/mfa/
grant_type: http://auth0.com/oauth/grant-type/password-realm
scope: enroll read:authenticators remove:authenticators offline_access openid picture name email
username: <your username>
password: <your password>

Example POST call to retrieve a token:

curl -s --request POST \
  --url 'https://dnsfilter.auth0.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"http://auth0.com/oauth/grant-type/password-realm", "client_id":"zJ1WJHavuUFx89cConwlipxoOc2J3TVQ", "realm":"Username-Password-Authentication", "audience": "https://dnsfilter.auth0.com/mfa/", "scope": "enroll read:authenticators remove:authenticators offline_access openid picture name email", "username": "<MY USERNAME>", "password": "<MY PASSWORD>"}'

In response to the call the access_token property is the JWT Token that is passed to our API.

After obtaining a JWT Token, the Authenticate may be called so Organization IDs and User IDs can be obtained. Many of our API calls require an Organization ID to be explicitly specified.

For more detailed information regarding this, please visit the API documentation linked at the top of this page. 

Persistent Tokens

DNSFilter could provide persistent JWT Tokens to avoid dealing with Auth0, please contact support (support@dnsfilter.com) to request one. Persistent JWT Tokens are ideal for API integrators.

Testing Authentication

After obtaining an authentication token as above, you can start using our API, for example:

curl --header "Authorization: token <JWTTOKEN>" --request POST "https://api.dnsfilter.com/v1/authenticate"

 

Third-Party Tools

Note:

This section is a work in progress and will eventually have import options for both Insomnia and Postman, where the user will just have to add their own access token to be able to run the calls.

The tools listed below may assist users when interacting, debugging or testing the API.

Insomnia

How to setup DNSFilter API within Insomnia (video guide in progress)

Postman

How to setup DNSFilter API within Postman (video guide in progress)

Import for postman found here: Postman

  • After importing the Postman setup above, click on the collection
  • Click on DNSFilter API
  • This will then open a box on the right with further options
  • Click on the Authorization tab
  • Input your API key in the Token box 
  • You will then be able to run the calls
    Note: Some calls will need user input for example the Domains > User_lookup call seen below:
    v1/domains/user_lookup?fqdn=<string>
    This requires a string on the end of it for example google.com, so it would look like this:
    v1/domains/user_lookup?fqdn=google.com

Requesting a Token with Two-factor Authentication

First, you retrieve your 2FA Token using the following. 
curl -s --request POST \
--url 'https://auth.dnsfilter.com/oauth/token' \
--header 'content-type: application/json' \
--data '{
"grant_type": "http://auth0.com/oauth/grant-type/password-realm",
"client_id": "zJ1WJHavuUFx89cConwlipxoOc2J3TVQ",
"realm": "Username-Password-Authentication",
"audience": "https://dnsfilter.auth0.com/mfa/",
"scope": "enroll read:authenticators remove:authenticators offline_access",
"username": "INSERTUSERNAME",
"password": "INSERTPASSWORD"
  }'
You will then receive a response after running this script which will give you an 2FA Token.
Add your 2FA Token into this script alongside your rotating OTP found on your authenticator app:
curl --request POST \
--url 'https://dnsfilter.auth0.com/oauth/token' \
--header 'content-type: application/json' \
--data '{
  "audience": "https://dnsfilter.auth0.com/mfa/",
  "grant_type": "http://auth0.com/oauth/grant-type/mfa-otp",
  "client_id": "zJ1WJHavuUFx89cConwlipxoOc2J3TVQ",
  "mfa_token": "INSERTMFATOKENHERE",
  "otp": "INSERTAUTHENTICATOROTPHERE",
  "realm": "Username-Password-Authentication",
  "scope": "enroll read:authenticators remove:authenticators offline_access"
  }'
You will then be handed a 600-second Access Token to be able to use. 
Note: The refresh token is found in the same response as the access token if you want to use the script below to refresh.
This can be refreshed using the below:
 curl --request POST \
--url 'https://dnsfilter.auth0.com/oauth/token' \
--header 'content-type: application/json' \
--data '{
"client_id": "zJ1WJHavuUFx89cConwlipxoOc2J3TVQ",
"grant_type": "refresh_token",
  "access_token": "INSERTACCESSTOKEN",
  "refresh_token": "INSERTREFRESHTOKEN"
    }'

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.