3.2. Notes on Authentication Requests and Responses

The sample requests and response in this section illustrate general cases. In your authentication request, use your own credentials rather than the sample values shown here for username, and key. When you authenticate successfully, the response to your authentication request will include a catalog of the services to which you have subscribed rather than the sample values shown here.

Example 3.1. Authentication Request with Headers: XML

POST /v1.1/auth HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml

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

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

In the following example, the content type is set to application/json but application/xml is requested via the Accept header.

Example 3.2. Authentication Request with Headers: JSON

POST /v1.1/auth HTTP/1.1
Host: identity.api.rackspacecloud.com
Content-Type: application/json
Accept: application/xml

{
    "credentials" : {
        "username" : "hub_cap",
        "key"  : "a86850deb2742ec3cb41518e26aa2d89"
    }
}

An alternative method of requesting authentication is illustrated below: in this example, a URI extension rather than an Accept header sets the content type.

Example 3.3. Authentication Request with Extension: JSON

POST /v1.1/auth.xml HTTP/1.1
Host: identity.api.rackspacecloud.com
Content-Type: application/json

{
    "credentials" : {
        "username" : "hub_cap",
        "key"  : "a86850deb2742ec3cb41518e26aa2d89"
    }
}

Whichever method is used to request authentication, a successful authentication response includes a token and a service catalog.

Example 3.4. Authentication Response with Headers: XML

HTTP/1.1 200 OK
Date: Mon, 12 Nov 2010 15:55:01 GMT
Server: Apache
Content-Length:
Content-Type: application/xml; charset=UTF-8

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

<auth  xmlns="http://docs.rackspacecloud.com/auth/api/v1.1">
  <token id="aaaaa-bbbb-cccc-ddddd" 
         expires="2012-04-12T13:15:52.000-05:00"/>
  <serviceCatalog>
    <service name="cloudDatabases">
      <endpoint 
          region="ORD" 
          v1Default="false"
          publicURL="https://ord.databases.api.rackspacecloud.com/v1.0/12345"/>
      <endpoint 
          region="DFW" 
          v1Default="false"
          publicURL="https://dfw.databases.api.rackspacecloud.com/v1.0/12345"/>
    </service>
    <service name="cloudDNS">
      <endpoint 
          v1Default="false" 
          publicURL="https://dns.api.rackspacecloud.com/v1.0/12345"/>
    </service>
    <service name="cloudFiles">
      <endpoint
          region="DFW"
          v1Default="true"
          publicURL="https://storage.clouddrive.com/v1/RackCloudFS_demo"
          internalURL="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="cloudLoadBalancers">
      <endpoint 
          region="DFW" 
          v1Default="false"
          publicURL="https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/12345"/>
      <endpoint 
          region="ORD" 
          v1Default="false"
          publicURL="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/12345"/>
    </service>
    <service name="cloudMonitoring">
      <endpoint 
          v1Default="false"
          publicURL="https://monitoring.api.rackspacecloud.com/v1.0/12345"/>
    </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>

	This token can be presented to a service as evidence of authentication. Tokens are valid for a finite duration; a token's default lifespan is twenty-four hours. 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.
	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), as well as one database service, one DNS service, one loadbalancing service, and one monitoring service. 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.
	The service name attribute identifies each unique service in the catalog. Once a service is created, its name does not change.
	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.
	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.
	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.

	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.

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/Sample_Request_Response-d1e64.html.

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/Sample_Request_Response-d1e64.html.

Legal notices