Locations --------- XML Authentication https://hexillion.com/rf/xml/1.0/auth/ ^ Note the "s". We recommend SSL for authentication. XML Whois http://hexillion.com/rf/xml/1.0/whois/ ^ Note lack of "s". We recommend *against* SSL for Whois. We recommend making these URLs configurable in your software instead of hard-coding them. Using the service with a session key (recommended) -------------------------------------------------- 1. Begin by authenticating the user and obtaining a session key. - Send username and password (as "username" and "password") in the URL for GET requests or in the body for POST requests. Remember to URL-encode the username and password if passing them in the URL. SECURITY NOTE: We recommend using POST requests with SSL (HTTPS) for maximum security during authentication. Without SSL your username and password will be visible to anyone with access to the intermediate networks (including your ISP and any fellow users of your open WiFi hotspot). If you use HTTP GET, your password parameter will be stored in plain text in our server logs and may be exposed if our server is ever compromised. In any case, use a strong password that you do not use for any other system. - The username and password may contain up to 50 characters each. The password is case-sensitive, but the username is not. - Session keys are strings of characters. Keys may vary in length and should be treated as opaque blobs. They expire if not used for 20 minutes. 2. Use the Whois service with the key. - Pass in the session key as "sessionkey" along with the other service inputs. 3. Close the session (optional but recommended). - Pass the session key back to the authorization service to close the session. If you don't do this, the session will expire automatically in 20 minutes However, explicitly closing the session reduces the risk of session hijacking. Example session: // Get session key // We're using HTTP GET to keep the example simple, but using HTTP POST // would be more secure. See the security note above. https://hexillion.com/rf/xml/1.0/auth/?username=XYZCorp&password=As42lg9o3 // Result from auth service Success The service successfully processed your request. nOIANdfjL4524ynjlssasjfDFaqe4 // Do Whois query, passing in session key http://hexillion.com/rf/xml/1.0/whois/?sessionkey=nOIANdfjL4524ynjlssasjfDFaqe4 &query=yahoo.com // Result from Whois service [usual XML result] // Close session https://hexillion.com/rf/xml/1.0/auth/?sessionkey=nOIANdfjL4524ynjlssasjfDFaqe4 Using the service without a session key --------------------------------------- Use the Whois service normally, but send in the username and password (as "username" and "password") every time along with the other inputs. This method is simpler but will incur a slight performance penalty on the server side and reduce security by sending the password over the network in plain text. Not recommended if you can avoid it. Using HTTP POST will at least keep the password out of the URL, which may be logged by proxies or other intermediate systems. Example (using HTTP GET): // Do Whois query, passing in username and password http://hexillion.com/rf/xml/1.0/whois/?username=XYZCorp&password=As42lg9o3 &query=yahoo.com AuthResult error codes ---------------------- Success - Successfully opened or closed a session AuthenticationFailed - The username or password was not correct InvalidSessionKey - The specified session key was malformed ServiceResult error codes (relevant to sessions) ------------------------------------------------ Success - Everything went OK with session check and query AuthenticationFailed - The session key expired or wasn't specified; or the username or password was not correct InvalidSessionKey - The specified session key was malformed RequestLimitReached - The user's account ran out of queries