Authenticate to the Rackspace Cloud

Whether you use cURL, a REST client, or a command-line client (CLI) to
send requests to the Customer Management Service, you need an
authentication token to include in the X-Auth-Token header of each
request. You get a token by submitting an authentication request with
valid account credentials to the following Identity API service
endpoint:

https://identity.api.rackspacecloud.com/v2.0

With a valid token, you can send API requests to any of the API service
endpoints that you are authorized to use. The authentication response
includes a token expiration date. When a token expires, you can send
another authentication request to get a new one.

For more information about authentication tokens, see the following
topics in the Identity developer documentation.

Authentication token operations

The examples in the Getting Started Guide show how to authenticate
by using username and API key credentials, which is a more secure
way to communicate with API services. The authentication token
operations reference describes other types of credentials that you
can use for authentication.
Manage tokens and token expiration

Follow these steps to authenticate to the Rackspace Cloud by
using cURL.

Send an authentication request

Review the authentication response

Configure environment variables

The cURL examples in this guide are provided for reference only. Because
the use of cURL has environmental dependencies, copying and pasting the
examples might not work in your environment.

Send an authentication request

From a command prompt, send a POST tokens request to the Rackspace
Cloud Identity service. Include your username and your credentials, as
shown in the following example.

$ curl https://identity.api.rackspacecloud.com/v2.0/tokens  \
-X POST \
-d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"yourUserName",
"apiKey":"$apiKey"}}}' \
-H "Content-type: application/json" | python -m json.tool

Review the authentication response

If your credentials are valid, the Identity service returns an
authentication response that includes the following information:

An authentication token

A service catalog with information about the services that you can
access

User information and role assignments

For detailed information about the authentication response, see the
Annotated authentication request and response
in the Rackspace Cloud API documentation.

In the following example, the ellipsis (...) represents other service
endpoints, which are not shown. The values shown in this and other
examples vary because the information returned is specific to your
account.

Example: Authentication response

{
   "access": {
   "token": {
     "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
     "expires": "2014-11-24T22:05:39.115Z",
     "tenant": {
       "id": "110011",
       "name": "110011"
     },
     "RAX-AUTH:authenticatedBy": [
       "APIKEY"
     ]
   },
   "serviceCatalog": [
   {
     "name": "cloudDatabases",
     "endpoints": [
      {
        "publicURL": "https://syd.databases.api.rackspacecloud.com/v1.0/110011",
        "region": "SYD",
        "tenantId": "110011"
      },
      {
        "publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/110011",
        "region": "DFW",
        "tenantId": "110011"
      },
      {
        "publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/110011",
        "region": "ORD",
        "tenantId": "110011"
      },
      {
        "publicURL": "https://iad.databases.api.rackspacecloud.com/v1.0/110011",
        "region": "IAD",
        "tenantId": "110011"
       },
       {
         "publicURL": "https://hkg.databases.api.rackspacecloud.com/v1.0/110011",
         "region": "HKG",
         "tenantId": "110011"
       }
      ],
      "type": "rax:database"
    },

    ...

    {
      "name": "cloudDNS",
      "endpoints": [
         {
             "publicURL": "https://dns.api.rackspacecloud.com/v1.0/110011",
             "tenantId": "110011"
         }
      ],
      "type": "rax:dns"
     },
     {
       "name": "rackCDN",
       "endpoints": [
         {
           "internalURL": "https://global.cdn.api.rackspacecloud.com/v1.0/110011",
           "publicURL": "https://global.cdn.api.rackspacecloud.com/v1.0/110011",
           "tenantId": "110011"
           }
       ],

       "type": "rax:cdn"
      }
    ],
    "user": {
      "id": "123456",
      "roles": [
      {
        "description": "A Role that allows a user access to keystone Service methods",
        "id": "6",
        "name": "compute:default",
        "tenantId": "110011"
      },
      {
        "description": "User Admin Role.",
        "id": "3",
        "name": "identity:user-admin"
      }
      ],
      "name": "jsmith",
      "RAX-AUTH:defaultRegion": "ORD"
    }
   }
}

If the request was successful, it returns the following values that you
need to include when you make service requests to the Rackspace product
API:

token ID
The token ID value is required to confirm your identity each time you
access the service. Include it in the X-Auth-Token header for each API
request.

The expires attribute indicates the date and time that the token will
expire, unless it is revoked before the expiration. To get a new token,
submit another authentication request. For more information, see
Manage tokens and token expiration

tenant ID
The tenant ID provides your account number. For most Rackspace Cloud
service APIs, the tenant ID is appended to the API endpoint in the
service catalog automatically. For Rackspace Cloud services, the tenant
ID has the same value as the tenant name.

endpoint
The API endpoint provides the URL that you use to access the API
service.

If the request failed, review the response message and the following
error message descriptions to determine next steps.

If you see the following error message, review the authentication
request for syntax or coding errors. If you are using cURL, see
Using cURL.
```
400 Invalid request body: unable to parse Auth data. Please review XML or
JSON formatting
```
If you see the following error message, verify the authentication
credentials submitted in the authentication request. If necessary,
contact your Rackspace Cloud Administrator or Rackspace Support to
get valid credentials.
```
401 Unable to authenticate user with credentials provided.
```

For additional information about authentication errors, see the
Identity API Reference documentation.

Configure environment variables

To make it easier to include the token ID, tenant ID, endpoint, and
other values in API requests, use the export command to create
environment variables that can be substituted for the actual values. For
example, you can create an ENDPOINT variable to store the URL for
accessing an API service. To reference the value in an API request,
prefix the variable name with a $, for example $ENDPOINT.

The environment variables created with the export command are valid
only for the current terminal session. If you start a new session, run
the export commands again.

To reuse the variables across sessions, update the configuration file
for your shell environment to include the export statements. For details
about using and managing environment variables on different systems, see
the environment variables wiki.

Create environment variables

In the token section of the authentication response, copy the
token id and tenant id values from the token object. The
following example shows example values only.

{
  "access": {
    "token": {
      "id": "AA2345631l1NVdD6D1OCauKA0e9fioquZqVlS-hpbCqQ5Yx1zLOREGf4efBh10CfB5AvjC1yld4ZNJUouE7DA0QB0n5nRbdDsYADA-ORICIqHNqOVS_kYmedqDh75c_PLe123456789101",
      "expires": "2015-11-18T18:35:45.013Z",
      "tenant": {
        "id": "123456",
        "name": "123456"
      },
      "RAX-AUTH:authenticatedBy": [
        "APIKEY"
      ]
 },

Export the token ID to an environment variable that can be supplied
in the X-Auth-Token header required in each API request.
```
$ export AUTH_TOKEN="token-id"
```
Replace token-id with the authentication token id value returned
in the authentication response.
Export the tenant ID to an environment variable that can be supplied
in requests that require you to specify a tenant ID or tenant name.
```
$ export TENANT_ID="tenant-id"
```
Replace tenant-id with the authentication token id value
returned in the authentication response.

In the service catalog section of the authentication response,
copy the publicURL value for the , version, and region that you
want to access.

This example shows the endpoints available for the .

{
  "endpoints": [
  {
    "publicURL": "https://syd.loadbalancers.api.rackspacecloud.com/v1.0/123456",
    "region": "SYD",
    "tenantId": "123456"
  },
  {
    "publicURL": "https://iad.loadbalancers.api.rackspacecloud.com/v1.0/123456",
    "region": "IAD",
    "tenantId": "123456"
  },
  {
    "publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/123456",
    "region": "ORD",
    "tenantId": "123456"
  },
  {
    "publicURL": "https://hkg.loadbalancers.api.rackspacecloud.com/v1.0/123456",
    "region": "HKG",
    "tenantId": "123456"
  },
  {
    "publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/123456",
    "region": "DFW",
    "tenantId": "123456"
  }
  ],
  "name": "cloudLoadBalancers",
  "type": "rax:load-balancer"
},

For some services, the publicURL value for the API consists of the
endpoint URL with the tenant ID for your account appended after the
final /.

Export the URL to an environment variable, as shown in the following
example:
```
$ export API_ENDPOINT="publicURL"
```
Replace publicURL with the publicURL value listed in the service
catalog.