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 only valid for 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.

  • 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 ReST client for Firefox.

 1.1. Generate an authentication token

  1. Get your Rackspace Cloud credentials.

    username and password

    The username and password are the same credentials that you use to log in to the Cloud Control panel.

    username and apiKey

    You can find your API key on the Account Settings page in the Cloud Control panel. After logging in, click your user ID. Then, select Account Settings from the menu.

    tenantId or tenantName (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.

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

    • Use your username and password:

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

      $ curl  \
       -X POST \
       -d '{"auth":{"RAX-KSKEY:apiKeyCredentials"{"username":"myUserName","apiKey":"thePassword"}}}' \
       -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 message in the response to determine next steps.

      Table 1.1. Authentication error messages
      Error Action

      message: 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 these 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 phone 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


      message: 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.


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

      Your Rackspace Cloud environment requires users to authenticate by using multi-factor authentication.


      message: 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.

 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, find the token ID in the token object and save it, or export it to an environment variable that can be supplied in the X-Auth-Token header required by each API request.

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

    For example, the endpoint for Cloud Files is

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

    This example shows a cURL request to retrieve a list of containers for a tenant by using he Cloud Files API.

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

    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 these 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 Keystone implementation.

    • Submit a DELETE token request to revoke the existing token 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 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...