Authentication

Each ReST request against the Cloud Servers system requires the inclusion of a specific authorization token HTTP x-header, defined as X-Auth-Token. Clients obtain this token, along with the Cloud Servers API URL, by first using the Rackspace Cloud Authentication Service and supplying a valid username and API access key.

The Rackspace Cloud Authentication Service is a ReSTful web service. It is the entry point to all Rackspace Cloud APIs.

To access the Authentication Service, you must know whether your account is US-based or UK-based:

US-based accounts authenticate through https://auth.api.rackspacecloud.com/v1.0.
UK-based accounts authenticate through https://lon.auth.api.rackspacecloud.com/v1.0.

Your account may be based in either the US or the UK; this is not determined by your physical location but by the location of the Rackspace retail site which was used to create your account:

If your account was created via http://www.rackspacecloud.com, it is a US-based account.
If your account was created via http:/www.rackspace.co.uk, it is a UK-based account.

If you are unsure how your account was created, use the Rackspace contact information at either site to ask for help.

Request

To authenticate, you must supply your username and API access key in x-headers:

Use your Rackspace Cloud username as the username for the API. Place it in the X-Auth-User x-header.
Obtain your API access key from the Rackspace Cloud Control Panel in the Your Account | API Access section. Place it in the X-Auth-User x-header.

Example 3.1. Authentication Request (US-Based Account)

GET /v1.0 HTTP/1.1
Host: auth.api.rackspacecloud.com
X-Auth-User: jdoe
X-Auth-Key: a86850deb2742ec3cb41518e26aa2d89

The Cloud Servers API may return any of the HTTP/1.1 response codes defined by RFC-2616 Section 10. If authentication is successful, an HTTP status 204 (No Content) is returned with three cloud service headers, X-Server-Management-Url, X-Storage-Url, X-CDN-Management-Url, as well as X-Auth-Token. An HTTP status of 401 (Unauthorized) is returned if authentication fails. All operations against Cloud Servers should be performed against the URL specified in X-Server-Management-Url (which is dynamic and subject to change) and must include the X-Auth-Token header as noted above. The URLs specified in X-Storage-Url and X-CDN-Management-Url are specific to the Cloud Files product and may be ignored for purposes of interacting with Cloud Servers.

Example 3.2. Authentication Response

HTTP/1.1 204 No Content
Date: Mon, 12 Nov 2007 15:32:21 GMT
Server: Apache
X-Server-Management-Url: https://servers.api.rackspacecloud.com/v1.0/35428
X-Storage-Url: https://storage.clouddrive.com/v1/CloudFS_9c83b-5ed4
X-CDN-Management-Url: https://cdn.clouddrive.com/v1/CloudFS_9c83b-5ed4
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Length: 0
Content-Type: text/plain; charset=UTF-8

Authentication tokens are typically valid for 24 hours. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response.

Note that API operation URIs specified throughout this document are relative, this is, they should be appended to the end of the X-Server-Management-Url that is returned from the authentication system. For example, in the sample response above, you would list servers by performing a GET against https://servers.api.rackspacecloud.com/v1.0/35428/servers.

Legal notices