API Tokens

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 can issue persistent JWT Tokens to eligible accounts to avoid Auth0, which is ideal for API integrators.

Account minimums/standings are used when determining eligibility for a persistent token. Contact our Support team to request one.

Test 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

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

Request 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"
    }'

DNSFilter.json
2 MB Download

How can we help you?

Search

In this article