Server-to-Server OAuth | Documentation | WHOIS API | WhoisXML API

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