Chapter 5. 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 Load Balancer 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 Access section (login here: Control Panel Login).

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 (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 5.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 5.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'

Example 5.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 5.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 `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 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 the services (for example https://servers.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 Load Balancers API calls, wherever you see the field your_acct_id specified in the examples in this guide.

Load balancer service endpoints are published in the service catalog in the Auth response with the account number, which is a required element of the service endpoints. The examples shown here are for authentication for US customers. Customers with UK-based accounts will see different values in the service catalog. Refer to Chapter 6, Service Access/Endpoints for more information about service endpoints.

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

Legal notices