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
orPOST
-
Authenticates you to our site and generates a session key to use in calls to our other services. You must supply
username
andpassword
as input.
NOTE
We recommend using
POST
requests for maximum security. If you useGET
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
orPOST
-
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.