Chapter 4. Generate an Authentication Token

You need to generate a token whether you use cURL or a ReST client.

In order to use the ReST API, you will first need to obtain an authentication token, which will need to be passed in for each request using the X-Auth-Token header.

The following example demonstrates how to use cURL to obtain the authentication token and the account number. You will need to supply the authentication token and account number when making subsequent Cloud Databases API calls.

Remember to replace the names in the Authenticate Request examples below with their respective values:

your_username — The username is your common Rackspace Cloud username, as supplied during registration.
your_api_key — The key is your API access key. The key can be obtained from the Rackspace Cloud Control Panel in the <Your Account> / API Keys section (login here: Cloud Control Panel).

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

US-based accounts authenticate through https://identity.api.rackspacecloud.com/v2.0/.
UK-based accounts authenticate through https://lon.identity.api.rackspacecloud.com/v2.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.

Notice that you authenticate using a special URL for Cloud authentication services. For example, for US-based accounts, you use https://identity.api.rackspacecloud.com/v2.0/tokens, as shown in the following Authenticate Request examples. Note that the v2.0 component in the URL indicates that you are using version 2.0 of the Cloud Auth API.

Example 4.1. cURL Authenticate Request: XML

curl -i -d \
'<?xml version="1.0" encoding="UTF-8"?>  
<auth>
   <apiKeyCredentials
      xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
         username="your_username" 
         apiKey="your_api_key"/>
</auth>' \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \
'https://identity.api.rackspacecloud.com/v2.0/tokens'

Example 4.2. cURL Authenticate Request: JSON

curl -i -d \
'{
    "auth":
    {
       "RAX-KSKEY:apiKeyCredentials":
       {  
          "username": "your_username",  
          "apiKey": "your_api_key"}
    }  
}' \
-H 'Content-Type: application/json' \
'https://identity.api.rackspacecloud.com/v2.0/tokens'

	Note
	For UK-based accounts, you would need to modify the URL shown in the last line of each of the Authenticate Request examples above to be `'https://lon.identity.api.rackspacecloud.com/v2.0/tokens'` instead.

Example 4.3. Authenticate Response: XML

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:50:20 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<access xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
  xmlns="http://docs.openstack.org/identity/api/v2.0"
  xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
  xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
  xmlns:common="http://docs.openstack.org/common/api/v1.0"
  xmlns:ksgrp="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
  xmlns:rax-kscatalog="http://docs.openstack.org/identity/api/ext/OS-KSCATALOG/v1.0"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <token id="vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz" expires="2011-12-08T22:51:02.000-06:00"/>
  <user id="123456" name="jsmith" rax-auth:defaultRegion="DFW">
    <roles>
      <role id="identity:admin" name="identity:admin" description="Admin Role."/>
      <role id="identity:default" name="identity:default" description="Default Role."/>
    </roles>
  </user>
  <serviceCatalog>
    <service type="rax:database" name="cloudDatabases">
      <endpoint region="DFW" tenantId="1100111" publicURL="https://dfw.databases.api.rackspacecloud.com/v1.0/1100111"/>
      <endpoint region="ORD" tenantId="1100111" publicURL="https://ord.databases.api.rackspacecloud.com/v1.0/1100111"/>
    </service>
    <service type="rax:load-balancer" name="cloudLoadBalancers">
      <endpoint region="DFW" tenantId="1100111" publicURL="https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/1100111"/>
      <endpoint region="ORD" tenantId="1100111" publicURL="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1100111"/>
    </service>
    <service type="compute" name="cloudServersOpenStack">
      <endpoint region="DFW" tenantId="1100111"
        publicURL="https://dfw.servers.api.rackspacecloud.com/v2/1100111">
        <version id="2" info="https://dfw.servers.api.rackspacecloud.com/v2/"
          list="https://dfw.servers.api.rackspacecloud.com/" />
      </endpoint>
      <endpoint region="ORD" tenantId="1100111"
        publicURL="https://ord.servers.api.rackspacecloud.com/v2/1100111">
        <version id="2" info="https://ord.servers.api.rackspacecloud.com/v2/"
          list="https://ord.servers.api.rackspacecloud.com/" />
      </endpoint>
    </service>
    <service type="compute" name="cloudServers">
      <endpoint tenantId="1100111"
        publicURL="https://servers.api.rackspacecloud.com/v1.0/1100111">
        <version id="1.0"
          info="https://servers.api.rackspacecloud.com/v1.0/"
          list="https://servers.api.rackspacecloud.com/"/>
      </endpoint>
    </service>
    <service type="object-store" name="cloudFiles">
      <endpoint region="DFW"
        tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
        publicURL="https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
        internalURL="https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>
      <endpoint region="ORD"
        tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
        publicURL="https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
        internalURL="https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>
    </service>
    <service type="rax:object-cdn" name="cloudFilesCDN">
      <endpoint region="DFW"
        tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
        publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/> 
      <endpoint region="ORD"
        tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
        publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>    
    </service>
    <service type="rax:dns" name="cloudDNS">
      <endpoint tenantId="1100111"
        publicURL="https://dns.api.rackspacecloud.com/v1.0/1100111"/>
    </service>
  </serviceCatalog>
</access>

Example 4.4. Authenticate Response: JSON

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:45:13 GMT

{
    "access": {
     
        "token": {
            "expires": "2011-12-08T22:51:02.000-06:00", 
            "id": "vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz"
        }, 
        "user": {
            "id": "123456", 
            "name": "jsmith",
            "RAX-AUTH:defaultRegion": "DFW",
            "roles": [
                {
                    "description": "Admin Role.", 
                    "id": "identity:admin", 
                    "name": "identity:admin"
                }, 
                {
                    "description": "Default Role.", 
                    "id": "identity:default", 
                    "name": "identity:default"
                }
            ]
        },
        "serviceCatalog": [
            {
                "endpoints": [
                    {
                        "publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/1100111", 
                        "region": "DFW", 
                        "tenantId": "1100111"
                    }, 
                    {
                        "publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/1100111", 
                        "region": "ORD", 
                        "tenantId": "1100111"
                    }
                ], 
                "name": "cloudDatabases", 
                "type": "rax:database"
            },
            {
                "endpoints": [
                    {
                        "publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/1100111", 
                        "region": "DFW", 
                        "tenantId": "1100111"
                    }, 
                    {
                        "publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1100111", 
                        "region": "ORD", 
                        "tenantId": "1100111"
                    }
                ], 
                "name": "cloudLoadBalancers", 
                "type": "rax:load-balancer"
            }, 
            {
                "endpoints": [
                    {
                        "tenantId": "1100111",
                        "region": "DFW",
                        "publicURL": "https://dfw.servers.api.rackspacecloud.com/v2/1100111", 
                        "versionId": "2", 
                        "versionInfo": "https://dfw.servers.api.rackspacecloud.com/v2/", 
                        "versionList": "https://dfw.servers.api.rackspacecloud.com/"
                    },
                    {
                        "tenantId": "1100111",
                        "region": "ORD",
                        "publicURL": "https://ord.servers.api.rackspacecloud.com/v2/1100111", 
                        "versionId": "2", 
                        "versionInfo": "https://ord.servers.api.rackspacecloud.com/v2/", 
                        "versionList": "https://ord.servers.api.rackspacecloud.com/"
                    }
                ],
                "name": "cloudServersOpenStack", 
                "type": "compute"
            },
            {
                "endpoints": [
                    {
                        "tenantId": "1100111", 
                        "publicURL": "https://servers.api.rackspacecloud.com/v1.0/1100111", 
                        "versionId": "1.0", 
                        "versionInfo": "https://servers.api.rackspacecloud.com/v1.0/", 
                        "versionList": "https://servers.api.rackspacecloud.com/"
                    }
                ],
                "name": "cloudServers", 
                "type": "compute"
            }, 
            {
                "endpoints": [
                    {
                        "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
                        "publicURL": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "region": "DFW" 
                    },
                    {
                        "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
                        "publicURL": "https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "region": "ORD" 
                    }
                ], 
                "name": "cloudFiles", 
                "type": "object-store"
            }, 
            {
                "endpoints": [  
                    {
                        "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "publicURL": "https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "region": "DFW"
                    },                
                    {
                        "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "publicURL": "https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", 
                        "region": "ORD"
                    }
                ],
                "name": "cloudFilesCDN", 
                "type": "rax:object-cdn"
            }, 
            {
                "endpoints": [
                    {
                        "tenantId": "1100111",
                        "publicURL": "https://dns.api.rackspacecloud.com/v1.0/1100111"
                    }
                ],
                "name": "cloudDNS", 
                "type": "rax:dns"
            }
        ]
    }
}

The authentication token id is returned along with an expires attribute that specifies when the token expires.

Notes

	Notes
For all response examples in this guide, the field values you receive in your responses will vary from those shown here since they will be specific to your account. The information shown in the Authenticate Response examples above is for US-based accounts. If you authenticate against the UK-endpoint for auth, you will see the service catalog information for UK-based accounts. The `id` attribute in the Authenticate Response specifies the authentication token. Tokens are valid for a finite duration. Remember to supply your authentication token wherever you see the field your_auth_token in the examples in this guide. 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. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.

For all response examples in this guide, the field values you receive in your responses will vary from those shown here since they will be specific to your account.
The information shown in the Authenticate Response examples above is for US-based accounts. If you authenticate against the UK-endpoint for auth, you will see the service catalog information for UK-based accounts.
The id attribute in the Authenticate Response specifies the authentication token. Tokens are valid for a finite duration.
Remember to supply your authentication token wherever you see the field your_auth_token in the examples in this guide.
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.
Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.

The publicURL endpoints for cloudDatabases (for example https://ord.databases.api.rackspacecloud.com/v1.0/1100111) are also returned in the response.

You will find the actual account number after the final '/' in the publicURL field. In this example, you can see that the account number is 1100111. You need to specify your account number on most of the Cloud Databases API calls, wherever you see the field your_acct_id specified in the examples in this guide.

After authentication, you can use cURL to perform GET, DELETE, and POST requests for the Cloud Databases API.

Legal notices