— celebrating 20 years

Skip to main content

Main menu
Home
Your account
Help
About us

Authentication API reference

This page provides technical information about using the Authentication API (“Auth”) to “log in” before using the Whois API or our CentralOps tools.

Contents

Overview

Auth takes your username and password as input, then provides you with a session key that you use with our other services. This session key expires after 20 minutes of idle time but remains current as long as the time between your requests does not exceed 20 minutes. Using a session key eliminates the need to send your username and password with every request and makes it possible to use unencrypted HTTP for your requests without sending your credentials in the clear.

Auth sends you the session key in a cookie as well as in the body of the HTTP response. If your HTTP client manages cookies for you, you don’t have to handle the session key yourself—your client will automatically send the cookie with each request. Otherwise, you can send the session key yourself as an input to each tool.

Base URL

https://hexillion.com/rf/xml/1.0/auth/
    ^ Note the "s".

We recommend making this URL configurable in your software instead of hard-coding it.


WARNING

We strongly recommend using HTTPS (HTTP over TLS or SSL) for authentication to protect the security of your credentials, even though it is not required at this time.



NOTE

Though the URL contains the string “xml”, the service can also produce other representations such as JSON.


HTTP methods

GET or POST

Authenticates you to our site and generates a session key to use in calls to our other services. You must supply username and password as input.


NOTE

We recommend using POST requests for maximum security. If you use GET with your password in the URL it will be stored in plain text in our server logs and may be exposed if our server is ever compromised.


Example request:

POST https://hexillion.com/rf/xml/1.0/auth/ HTTP/1.1
Host: hexillion.com
Accept: application/vnd.hexillion.auth-v2+xml
Content-Type: application/x-www-form-urlencoded
Content-Length: 35

username=XYZCorp&password=As42lg9o3

Response from the server:

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2013 06:35:14 GMT
Set-Cookie: HexillionSession=7751367e04ce88408867593c0137aa842412ab4bffd14a43fe0b2eca4f835327; path=/; HttpOnly
Cache-Control: no-cache
Content-Type: application/vnd.hexillion.auth-v2+xml; charset=utf-8
Content-Length: 812

<?xml version="1.0" encoding="utf-8"?>
<AuthResult xmlns="https://hexillion.com/namespaces/auth/v2">
  <ErrorCode>Success</ErrorCode>
  <Message>The service successfully processed your request.</Message>
  <SessionKey>7751367e04ce88408867593c0137aa842412ab4bffd14a43fe0b2eca4f835327</SessionKey>
  <Accounting>
    <QueryDate>2015-03-25T05:16:43Z</QueryDate>
    <QueryCost>0</QueryCost>
    <Username>XYZCorp</Username>
    <UserIPAddress>192.0.2.1</UserIPAddress>
    <CurrentBalance>98525</CurrentBalance>
    <BalanceAfterLastRefill>100016.5</BalanceAfterLastRefill>
    <LastRefillDate>2014-06-01T10:46:00Z</LastRefillDate>
    <EstimatedDepletionDate>2068-11-12T02:31:00Z</EstimatedDepletionDate>
    <UsageRateSinceLastRefill>152.865</UsageRateSinceLastRefill>
  </Accounting>
</AuthResult>
GET or POST

For backward compatibility, it is also possible to invalidate your session key (that is, close your session) by sending a request with sessionKey as input.

Example request:

POST https://hexillion.com/rf/xml/1.0/auth/ HTTP/1.1
Host: hexillion.com
Accept: application/vnd.hexillion.auth-v2+xml
Content-Type: application/x-www-form-urlencoded
Content-Length: 75

sessionKey=7751367e04ce88408867593c0137aa842412ab4bffd14a43fe0b2eca4f835327

Response from the server:

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2013 06:35:14 GMT
Set-Cookie: HexillionSession=; expires=Fri, 29-Jun-2012 22:57:01 GMT; path=/
Set-Cookie: HexillionUser=; expires=Fri, 29-Jun-2012 22:57:01 GMT; path=/
Cache-Control: no-cache
Content-Type: application/vnd.hexillion.auth-v2+xml; charset=utf-8
Content-Length: 222

<?xml version="1.0" encoding="utf-8"?>
<AuthResult xmlns="https://hexillion.com/namespaces/auth/v2">
  <ErrorCode>Success</ErrorCode>
  <Message>The service successfully processed your request.</Message>
</AuthResult>

Input

Data model

Auth accepts three arguments:

username
Your Hexillion/CentralOps username (case-insenstive) as a string of up to 50 characters.
password
The password for your username as a case-sensitive string of up to 50 characters.
sessionKey
A current session key that you want to invalidate. This should be treated as an opaque character string of variable length.

Formats

Use application/x-www-form-urlencoded in the bodies of POST requests or the query portion of the URL in GET requests. (The typical percent-encoded name-value pairs, essentially.) Whether using GET or POST, any non-ASCII characters in the input must be encoded as UTF-8 prior to further encoding.

Output

Data model

All responses will contain an AuthResult in the body with an ErrorCode and a descriptive Message string. A response may also contain a SessionKey string and an Accounting section.

Possible values for ErrorCode are:

Success
The call to Auth succeeded.
AuthenticationFailed
The username or password wasn’t recognized.
InvalidSessionKey
The session key supplied was malformed (perhaps truncated) or is now invalid due to a software update on the server.
Unexpected
Something unexpected went wrong on the server.

The Accounting section provides a convenient accounting of the cost to service the request (which will be 0 for Auth) and information about your account balance and usage.

Formats

All response bodies are encoded in UTF-8. Use the HTTP Accept header in your requests to select one of the following MIME types for the response:

application/vnd.hexillion.auth-v2+xml
Version 2 XML format.
application/vnd.hexillion.auth-v2+json
Version 2 JSON format.
anything else
The original XML format served as text/xml for backward compatibility.

© 1997–2017