Rackspace ManualsCloud DNS Developer Guide  - API v1.0

  Atom feed of this document
 

3.1. Authentication

3.1.1. Geographic Endpoints
3.1.2. Retrieving the Authentication Token

Every ReST request against the DNS Service requires the inclusion of a specific authorization token, supplied by the X-Auth-Token HTTP header. Customers obtain this token by first using the Rackspace Cloud Authentication Service and supplying a valid username and API access key.

The Rackspace Cloud Authentication Service serves as the entry point to all Rackspace Cloud APIs and is itself a ReSTful web service.

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

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 you are unsure how your account was created, use the Rackspace contact information at either site to ask for help.

Verb URI Description
POST /auth Authenticate to receive a token and a service catalog.

Normal Response Code(s): 200, 203

Error Response Code(s): unauthorized (401), userDisabled (403), badRequest (400), authFault (500), serviceUnavailable (503)

The authenticate operation provides clients with an authentication token and a list of regional cloud endpoints.

Example 3.1. Auth Request: XML

<?xml version="1.0" encoding="UTF-8"?>

<credentials xmlns="http://docs.rackspacecloud.com/auth/api/v1.1"
             username=(1)"hub_cap"
             key=(2)"a86850deb2742ec3cb41518e26aa2d89"/>

Example 3.2. Auth Request: JSON

{
    "credentials":{
        "username":(1)"hub_cap",
        "key":(2)"a86850deb2742ec3cb41518e26aa2d89"
    }
}

1

The username supplied here is your common Rackspace Cloud username.

2

The key is your API access key. The key can be obtained from the Rackspace Cloud Control Panel in the Your Account / API Access section.

Example 3.3. Auth Response: XML

<?xml version="1.0" encoding="UTF-8"?>

<auth  xmlns="http://docs.rackspacecloud.com/auth/api/v1.1">
  <token id="asdasdasd-adsasdads-asdasdasd-adsadsasd"
         expires=(1)"2010-11-01T03:32:15-05:00" />
  <serviceCatalog(2)>
    <service name=(3)"cloudFiles">
      <endpoint
          region=(4)"DFW"
          v1Default=(5)"true"
          publicURL=(6)"https://storage.clouddrive.com/v1/RackCloudFS_demo"
          internalURL=(7)"https://storage-snet.clouddrive.com/v1/RackCloudFS_demo" />
      <endpoint
          region="ORD"
          publicURL="https://otherstorage.clouddrive.com/v1/RackCloudFS_demo"
          internalURL="https://otherstorage-snet.clouddrive.com/v1/RackCloudFS_demo" />
    </service>
    <service name="cloudFilesCDN">
      <endpoint
          region="DFW"
          v1Default="true"
          publicURL="https://cdn.clouddrive.com/v1/RackCloudFS_demo" />
      <endpoint
          region="ORD"
          publicURL="https://othercdn.clouddrive.com/v1/RackCloudFS_demo" />
    </service>
    <service name="cloudServers">
      <endpoint
          v1Default="true"
          publicURL="https://servers.api.rackspacecloud.com/v1.0/322781" />
    </service>
    <service name="cloudServersOpenStack">
      <endpoint
          region="DFW"
          v1Default="false"
          publicURL="https://dfw.servers.api.rackspacecloud.com/v2/322781" />
    </service>
  </serviceCatalog>
</auth>

Example 3.4. Auth Response: JSON

{
    "auth":{
        "token":{
            "id":"asdasdasd-adsasdads-asdasdasd-adsadsasd",
            "expires":(1)"2010-11-01T03:32:15-05:00"
        },
        "serviceCatalog"(2):{
            "cloudFiles"(3):[
                {
                    "region":(4)"DFW",
                    "v1Default":(5)true,
                    "publicURL":(6)"https://storage.clouddrive.com/v1/RackCloudFS_demo",
                    "internalURL":(7)"https://storage-snet.clouddrive.com/v1/RackCloudFS_demo"
                },
                {
                    "region":"ORD",
                    "publicURL":"https://otherstorage.clouddrive.com/v1/RackCloudFS_demo",
                    "internalURL":"https://otherstorage-snet.clouddrive.com/v1/RackCloudFS_demo"
                }
            ],
            "cloudFilesCDN":[
                {
                    "region":"DFW",
                    "v1Default":true,
                    "publicURL":"https://cdn.clouddrive.com/v1/RackCloudFS_demo"
                },
                {
                    "region":"ORD",
                    "publicURL":"https://othercdn.clouddrive.com/v1/RackCloudFS_demo"
                }
            ],
            "cloudServers":[
                {
                    "v1Default":true,
                    "publicURL":"https://servers.api.rackspacecloud.com/v1.0/322781"
                }
            ],
            "cloudServersOpenStack" : [
                {
                    "v1Default":false,
                    "publicURL":"https://dfw.servers.api.rackspacecloud.com/v2/322781", 
                    "region":"DFW"
                }    
            ]
        }
    }
}

1

This token can be presented to a service as evidence of authentication. Tokens are valid for a finite duration.

The expires attribute denotes the time after which the token will automatically become invalid. A token may be manually revoked before the time identified by the expires attribute; expires predicts a token's maximum possible lifespan but does not guarantee that it will reach that lifespan. Clients are encouraged to cache a token until it expires.

2

The service catalog lists the services this user can access. In this example, the user can access two compute services (Cloud Servers OpenStack and Cloud Servers) and two object storage services (Cloud Files Content Distribution Network (CDN), and Cloud Files). The catalog listing for each service provides at least one endpoint URL for that service. Other information, such as regions and versions and tenants, is provided if it's relevant to this user's access to this service.

3

The service name attribute identifies each unique service in the catalog. Once a service is created, its name does not change.

4

A service may expose endpoints in different regions. Regional endpoints allow clients to provision resources in a manner that provides high availability.

Some services are not region-specific. These services supply a single non-regional endpoint and do not provide access to internal URLs.

5

The v1Default attribute denotes that an endpoint is being returned in version 1.0 of the Cloud Authentication Service. The default value of v1Default is false; clients should assume the value is false when the attribute is missing. Auth 1.0 does not offer support for regional endpoints and therefore only returns one endpoint per service. Resources stored in endpoints where v1Default is false will not be seen by Auth 1.0 clients.

67

An endpoint can be assigned public and internal URLs. A public URL is accessible from anywhere. Access to a public URL usually incurs traffic charges. Internal URLs are only accessible to services within the same region. Access to an internal URL is free of charge.

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

[Important]Important

If you are programmatically parsing an authentication response, please be aware that service names are stable for the life of the particular service and can be used as keys. You should also be aware that a user's service catalog can include multiple uniquely-named services which perform similar functions. For example, cloudServersOpenStack is the OpenStack version of compute whereas cloudServers is the legacy version of compute; the same user can have access to both services. In Auth 2.0, the service type attribute can be used as a key by which to recognize similar services; see the tip below.

[Tip]Tip

Beginning with Auth 2.0, the service catalog includes a service type attribute to identify services that perform similar functions but have different names; for example, type="compute" identifies compute services such as cloudServers and cloudServersOpenStack. Some developers have found the service type attribute to be useful in parsing the service catalog. For Auth 2.0 (also known as the Cloud Identity Service), you can see the service type attribute in the "Authentication Response with Headers" sample in the Cloud Identity Client Developer Guide at http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Request_Response_Types-d1e149.html.

[Note]Note

Currently, DNS service endpoints are not published in the Auth response with the account number, which is a required element of the service endpoints. Refer to the next section for details about service endpoints.

Legal notices