3.1.1. Retrieving the authentication token

The authenticate operation provides users with an authentication token and a list of regional cloud endpoints. The sample requests and responses in this section illustrate a general case. In your authentication request, use your own credentials rather than the sample values shown for username and apiKey. When you authenticate successfully, the response to your authentication request includes a catalog of the services to which you have subscribed rather than the sample values shown.

The following table describes a request for an authentication token and the examples that follow show the request and response in JSON format.

Table 3.1. Request for Authentication Token
POST v2.0/tokens 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)

 

Example 3.1. Authentication request for US endpoint: JSON

                                POST /v2.0/tokens HTTP/1.1
User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6
Host: identity.api.rackspacecloud.com
Accept: application/json
Content-Type: application/json
Content-Length: 54

{
   "auth":
   {
      "RAX-KSKEY:apiKeyCredentials":
      {
         "username": (1)"jsmith",
         "apiKey": (2)"aaaaabbbbbccccc12345678"
      }
   }
}

                            

1

The username supplied here is your common Rackspace Cloud user name.

2

The key is your API access key. You can obtain the key from the Rackspace Cloud Control Panelin the <Your Account> / API Access section.

 

Example 3.2. Authentication response for US endpoint: JSON

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

{
    "access": {
     
       (1) "token": {
            "expires": "2013-08-09T22:51:02.000-06:00",
            "id": "vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz"
        },
        "user": {
            "id": "123456",
            "name": "jsmith",
           (2) "RAX-AUTH:defaultRegion": "DFW",
           (3) "roles": [
                {
                    "description": "Admin Role.",
                    "id": "identity:admin",
                    "name": "identity:admin"
                },
                {
                    "description": "Default Role.",
                    "id": "identity:default",
                    "name": "identity:default"
                }
            ]
        },
       (4) "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"
            },
            {
               (5) "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"
            },
            {
               (6) "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"
            },
            {
               (7) "endpoints": [
                    {
                        "publicURL": "https://monitoring.api.rackspacecloud.com/v1.0/1100111",
                        "tenantId": "1100111"
                    }
                ],
                "name": "cloudMonitoring",
                "type": "rax:monitor"
            },
            {
               (8) "endpoints": [
                    {
                        "publicURL": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/1100111",
                        "region": "DFW",
                        "tenantId": "1100111",
                        "versionId": "1.0",
                        "versionInfo": null,
                        "versionList": null
                    },
                    {
                        "publicURL": "https://ord.autoscale.api.rackspacecloud.com/v1.0/1100111",
                        "region": "ORD",
                        "tenantId": "1100111",
                        "versionId": "1.0",
                        "versionInfo": null,
                        "versionList": null
                    }
                ],
                "name": "autoscale",
                "type": "rax:autoscale"
            }, 
            {
                "endpoints": [
                    {
                       (9) "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
                       (10) "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",
                       (11) "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"
                    }
                ],
               (12) "name": "cloudFiles",
               (13) "type": "object-store"
            },
            {
                "endpoints": [
                    {
                        "tenantId": "1100111",
                        "publicURL": "https://dns.api.rackspacecloud.com/v1.0/1100111"
                    }
                ],
                "name": "cloudDNS",
                "type": "rax:dns"
            }
        ]
    }
}

                            

[Note]Note

The information shown in the authentication response example is for US-based accounts. If you authenticate against the UK endpoint, the response you receive shows the service catalog information for UK-based accounts.

1

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 24 hours.

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

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.

[Note]Note

The token's expiration time is formatted differently in the US and UK. These response examples show the US format. For examples of the UK format, see http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/POST_authenticate_v2.0_tokens_.html.

2

Users can be assigned a default region. If multiple endpoints are associated with a service in the user's catalog, the endpoint for the user's default region is selected if it is available. In this example, the user's default region is DFW, and several of the services in the user's catalog offer endpoints in that region and the ORD region; whenever possible, the user's work is directed to the DFW region.

3

Users can be assigned multiple roles, with each role providing specific privileges. In this example, jsmith is the administrative user for the account and holds the fully-privileged identity:admin role. Other users might hold other roles with different privileges. Roles are not necessarily associated with actual job functions such as Administrator, Operator, Developer, Tester, or Trainer.

4

The service catalog lists the services this user can access. In this example, the user can access one database service, one load-balancing service, one compute service (Cloud Servers OpenStack), one object storage service (Cloud Files), one monitoring service (Cloud Monitoring), one autoscale service (Rackspace Auto Scale), and one DNS service. The catalog entry for each service provides at least one endpoint URL for that service. Other information, such as regions, versions, and tenants, is provided if it is relevant to a user's access to a service.

5

This service catalog entry describes a load-balancing service. To use Rackspace Auto Scale, you must have access to a load-balancing service.

6

This service catalog entry describes a compute service. To use Rackspace Auto Scale, you must have access to a compute service.

7

This service catalog entry describes a monitoring service. To use Rackspace Auto Scale, you must have access to a monitoring service.

8

This service catalog entry describes Rackspace Auto Scale.

9

Some services recognize the specification of a tenant. If a service does recognize tenants, the format of the tenant specification is defined only by the service. For details about whether and how to specify a tenant, check the documentation for the service that you are using.

10

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 accessible only to services within the same region. Access to an internal URL is free of charge.

11

A service can expose endpoints in different regions. Regional endpoints allow users 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.

12

The service name attribute identifies each unique service in the catalog. After a service is created, its name does not change. However, new services of the same service type can be added to the catalog with new names.

[Important]Important

If you are programmatically parsing an authentication response, use service type rather than service name to determine whether a user has access to a particular kind of service. Service type is stable across all releases. New service types might be developed, but existing service types are not renamed. It is possible to subscribe to multiple services of the same type. Whatever those services are named, you can always recognize them by parsing for service type in the authentication response's service catalog.

13

The service type attribute identifies services that perform similar functions, regardless of service names. In this example, the service named cloudFiles is identified as type="store", indicating that it is a storage service even though the word "storage" does not appear in its name.

[Important]Important

Use service type as the primary value for locating a service. If multiple endpoints of the same service type exist in the same region, use service name to locate the appropriate service.



loading table of contents...