API

Updated November 23, 2023 15:56

Overview

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 MFA

First, you retrieve your MFA 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 MFA Token.

Add your MFA 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"
    }'

API