Chapter 1. Quickstart

Every REST request against Rackspace Cloud APIs requires an authentication token generated by the Identity service.

You obtain a token by submitting an authentication request with valid credentials to the Rackspace Cloud Identity service. The Identity service returns a response that includes an authentication token, user information and role assignments, and a service catalog with information about the available services.

With a valid token, you can submit API requests to any of the API service endpoints included in the service catalog. A token is valid for only 24 hours, which means that you must generate a new token each day.

Use this Quick Start to learn how to authenticate and submit API requests and to manage authentication tokens for Rackspace Cloud accounts. The instructions use cURL commands to provide direct access to the Cloud service API. The cURL command line tool is useful for running, testing, and troubleshooting individual API operations.

  • For additional authentication examples including authenticating as a Racker or by using impersonation, see the Token operations API reference.

  • If you are developing applications or automation for Rackspace Cloud services, try interacting with the Rackspace Cloud API services by using Rackspace SDKs or OpenStack client applications.

  • For API testing and workflow management in a graphical environment, try interacting with the API by using an application such as Postman or RESTClient for Firefox.

 1.1. Generate an authentication token

Perform the following steps to generate an authentication token.

  1. Get your Rackspace Cloud credentials.

    user name and password

    Your user name and password are the same credentials that you use to log in to the Cloud Control panel.

    user name and API key

    You can find your API key on the Account Settings page in the Cloud Control Panel. After logging in, click Account:yourUserName in the top-right corner, and then select Account Settings from the menu.

    tenant ID or tenant name (optional)

    Specify either the tenant ID or the tenant name for the specified user account.

    Administrative users can also authenticate by using tenant ID and token credentials.

    If you do not have these credentials, submit a ticket to the Nebulous Operations team, asking them to create a service account and provide credentials.

  2. Submit a POST tokens request with valid credentials to the Identity service API endpoint as shown in the following cURL example:

    • Use your user name and password:

      $ curl  \
       -X POST \
       -d '{"auth":{"passwordCredentials":{"username":"yourUserName","password":"yourPassword"}}}' \
       -H "Content-type: application/json" | python -m json.tool
    • Use your user name and API key:

      $ curl  \
       -X POST \
       -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"yourUserName","apiKey":"yourPassword"}}}' \
       -H "Content-type: application/json" | python -m json.tool
  3. Check the authentication response.

    • If the request is successful, use the information in the authentication response to submit an API request.

    • If the request is not successful, review the response message and the following error message descriptions to determine next steps.

      400 Invalid request body: unable to parse Auth data. Please review XML or JSON formatting.

      Review the authentication request for syntax or coding errors. If you are using cURL, see How cURL commands work.

      401 Additional authentication credentials required

      You are requesting authentication for an account that requires multi-factor authentication. To complete the authentication process, submit a second POST tokens request with the following credentials:

      • The session ID value returned in the WWW-Authenticate: OS-MF sessionId header parameter included in the response to the initial authentication request.

      • The passcode from the mobile device associated with your user account.


        Example 1.1. Authentication request with multi-factor authentication credentials

        $curl \
               -X POST \
               -d '{"auth": {"RAX-AUTH:passcodeCredentials": {"passcode":"1411594"}}}'\
               -H "X-SessionId: $SESSION_ID" \
               -H "Content-Type: application/json" --verbose | python -m json.tool

      401 Unable to authenticate user with credentials provided.

      Verify the authentication credentials submitted in the authentication request. If necessary, contact your Rackspace Cloud Administrator or Rackspace Support to get valid credentials.

      403 setup-mfa: You must first enable multifactor for this account. Please request a scoped setup-mfa token to set up MFA on your account.

      Your Rackspace Cloud environment requires users to authenticate by using multi-factor authentication. To enable this feature, request a scoped setup-mfa token and use it to authenticate and configure your account.


      You can find additional error message information in the Token operations API reference.

 1.2. Submit an API request to a Rackspace Cloud service

After you authenticate successfully, use the information in the authentication response to submit an API request for any service included in the service catalog.

  1. In the authentication response, copy the token id value from the token object and save it, or export it to an environment variable that can be supplied in the X-Auth-Token header required in each API request. In this example, the token value is 123abc5368901230076b12357897898.

            "RAX-AUTH:authenticatedBy": [
            "expires": "2014-01-09T15:08:53.645-06:00",
            "id": "123abc5368901230076b12357897898"
  2. Find the endpoint URL for the service that you want to access.

    For example, the endpoint URL for Cloud Files is

  3. Submit an API request to the service endpoint that you identified.

    The following example shows a cURL request to retrieve a list of containers for a tenant by using the Cloud Files API.

    $ cURL -i -s \
    -X GET \
    -H "X-Auth-Token: $AUTH_TOKEN" \
    -H "Content-type: application/json"  --verbose | python -m json.tool

    If the authentication token is accepted, the Cloud Files service returns the following response if the authentication token is accepted.

                        > GET /v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f HTTP/1.1
                        > User-Agent: curl/7.30.0
                        > Host:
                        > Accept: */*
                        > X-Auth-Token: 69dc089d983f4729af29bec5a7dc6426
                        > Content-type: application/json
                        HTTP/1.1 200 OK 
                        Content-Length: 22
                        X-Account-Object-Count: 0
                        X-Account-Storage-Policy-Policy-0-Bytes-Used: 0
                        X-Timestamp: 1345588196.72805
                        X-Account-Storage-Policy-Policy-0-Object-Count: 0
                        X-Account-Meta-Temp-Url-Key: e1f97840118eafc550d45dbd8e530c11
                        X-Account-Bytes-Used: 0
                        X-Account-Container-Count: 3
                        Content-Type: text/plain; charset=utf-8
                        Accept-Ranges: bytes
                        X-Trans-Id: tx1353de66dd9d49da84eda-00544799f4ord1
                        Date: Wed, 22 Oct 2014 11:50:12 GMT
                        * Connection #0 to host left intact

 1.3. Manage authentication tokens

Authentication tokens are valid for 24 hours by default. The expiration time stamp is included in the token object returned in the authentication response. Administrators and users can invalidate a token immediately by submitting a Revoke token API request to the Identity service endpoint.

If you re-authenticate before the token expires, the Identity service returns the same token as long as it remains valid.

When a token expires or becomes invalid, any API request submitted against Rackspace Cloud services returns a 401 error message. To regain access, submit another POST tokens request to the authentication endpoint.

Best practices
  • Cache authentication tokens.

    By default, the Rackspace Cloud Identity service makes an authentication request before every API call.

    To speed up your API operations and reduce system load, store the authentication token in a secure cache or database so that the API can use the stored information, instead of having to re-authenticate for each API request. You can re-use the cached token value as long as it remains valid.

  • Design applications to re-authenticate after receiving a 401 Unauthorized response from a service endpoint, or use either of the following methods to get a new token before the existing token expires.

    • Submit a POST tokens request within an hour of the token expiration to obtain a new token. Note that this behavior is a Rackspace customization of the OpenStack Identity (keystone) implementation.

    • Submit a DELETE token request to revoke the existing token, and then followed by a POST tokens request to get a new token.

  • To simplify authentication, credential, and token management, use an OpenStack command-line client application or one of the Rackspace SDKs.

 1.4. Learn more

Visit the following links to learn more about the Identity service.


You can find language binding examples that can be modified to work with the Cloud Identity service in the Rackspace Software Development Kits.

Contents Search
loading table of contents...