Server-to-Server OAuth

Use server-to-server OAuth to authenticate with WhoisXML APIs when making API requests. This is also known as two-legged OAuth as it uses a two step process flow that does not require user interaction for authentication or authorization. Here's the flow.

Your server-to-server OAuth client requests an access token from the WhoisXML API authorization server.
Your client uses the access token to make API requests.

You can also check this script on GitHub for an example of how to use the WHOIS API with Server-Side SSO.

Generate an access token

Use the accessToken grant type to generate an access token. The features of this grant type are:

The token's lifetime is 1800 (30 mins), 3600 (1 hour), 7200 (2 hours), or 10800 seconds (3 hours). Default is 3600 seconds (1 hour).
There is no refresh token.
You can generate and use multiple access tokens.
When the new API key is generated, all previously generated access tokens are invalidated.
The access tokens generated are valid for any product to which you have access.

Please note that the generated accessToken is used instead of the apiKey parameter in API requests.

API endpoint

POST https://main.whoisxmlapi.com/oauth/token

curl --location 'https://main.whoisxmlapi.com/oauth/token' \
--header 'Authorization: Bearer %base64_encoded_API_key%' \
--header 'Content-Type: application/json' \
--data '{
    "grantType": "access_token",
    "expiresIn": 7200
}'

Headers

Authorization

Required. Base64 encoded API key.

Authentication scheme: Bearer.

Get your personal API key on the My products page.

Input parameters

grantType	Required. The grant type to generate an access token. Acceptable values: access_token.
expiresIn	Optional. The lifetime of the access token in seconds. Acceptable values: 1800, 3600, 7200, 10800. Default: 3600.
outputFormat	Optional. Response output format. Acceptable values: JSON \| XML Default: JSON

Response

{
    "accessToken": "G2OIE2AKRCVDYFUJCV5PXXXXXXXXXXXX",
    "expiresIn": 3600
}

Use the accessToken value in the response to authenticate your API requests. Substitute the resulting value into the apiKey field as you would with a normal API key without OAuth.

Errors

{
    "code": 401,
    "messages": "Access restricted. Check the credits balance or enter the correct API key."
}

{
    "code": 422,
    "messages": {
        "grantType": [
            "The selected grant type is invalid."
        ]
    }
}

Example of cURL WHOIS API GET request with access token

curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com' \
--header 'Authorization: Bearer %accessToken%'

Example of cURL WHOIS API POST request with access token

curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer %accessToken%' \
    --data '{
        "domainName": "google.com"
    }'

WHOIS / WHOIS History

DNS / DNS History

IP Geolocation / IP Netblocks

Domain Research Suite (DRS)

Domain/WHOIS

DNS/IP

Intelligence

Other

Domain/WHOIS

DNS/IP

Intelligence

Other

Domain/WHOIS

DNS/IP

Intelligence

Other

Domain Research Suite (DRS)

Research

Monitoring

White-Label

Predictive Threat Intelligence

Internet Infrastructure

Enterprise API Packages

Security Intelligence (SI) Suite

Server-to-Server OAuth

Generate an access token

API endpoint

Headers

Input parameters

Response

Errors

Example of cURL WHOIS API GET request with access token

Example of cURL WHOIS API POST request with access token

Have questions?