Quick Start

Every ReST request against Rackspace Cloud APIs requires an authentication token generated by the Rackspace Cloud Identity Service.

To generate an authentication token, issue an authentication request to the Rackspace Cloud Identity Service, an implementation of the OpenStack Keystone Identity Service v2.0. In response to valid credentials, the Identity service returns a token object, user information, and a service catalog that includes a list of services that you can access with the supplied token. The token object provides a token ID and an expiration timestamp, which is set to 24 hours by default.

You can access an API by including the token in requests to the API service endpoint. When the token expires, the Identity service returns a 401 error message. To get a new token, submit another authentication request to the Identity API endpoint.

The following sections describe how to authenticate, submit an API request, and manage authentication tokens.

 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 submitting tenantId and token credentials. For details, see Authenticate as tenant with token.

  2. Choose either of the following Identity service API endpoints to submit the authentication request:

  3. Submit a POST tokens request with valid credentials to the chosen endpoint as shown in the following cURL example:

    • Use your username and password:

      $ curl https://identity.api.rackspacecloud.com/v2.0/tokens  \
       -X POST \
       -d '{"auth":{"passwordCredentials":{"username":"theUserName","password":"thePassword"}}}' \
       -H "Content-type: application/json"
    • Use your username and API key:

      $ curl https://identity.api.rackspacecloud.com/v2.0/tokens  \
       -X POST \
       -d '{"auth":{"RAX-KSKEY:apiKeyCredentials"{"username":"myUserName","apiKey":"thePassword"}}}' \
       -H "Content-type: application/json"
  4. Review the authentication response which includes a token object, a service catalog with available API endpoints, and user information.

    • If the request is successful, locate the token ID in the token object and save it, or export it to an environment variable to include in subsequent requests to Rackspace Cloud service API endpoints.

      "token": 
            {
              "RAX-AUTH:authenticatedBy": [
                  "PASSWORD"
                      ],
              "expires": "2014-01-09T15:08:53.645-06:00",
              "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
    • If your account is enabled for multi-factor authentication, the Identity service sends an SMS message with a passcode to the phone associated with your account and returns a 401 message that includes a sessionId in the WWW-Authenticate header.

      < HTTP/1.1 401 Unauthorized
      * Server Apache-Coyote/1.1 is not blacklisted
      < Server: Apache-Coyote/1.1
      < vary:  Accept, Accept-Encoding, X-Auth-Token
      < WWW-Authenticate: OS-MF sessionId='APU9ymMBWY5W-pTgnHuZEvjKsM5oG_ler4lC0g_EkCPYvPdUBHK55RWtsgpL5RZ22AyDNaVCNCz6mlDOwbJAI-RLFQywI7CgOvjH0MLhL5a6D-c4cd1x8BbZmy8uT8ejm7jzBUX_vDZ5R0Hcia5DkOB80yWNJ8XVKMxVYLg5Qwp0TPA2zx-HQOTM3xqVQE63u1mYDUqikrXQ', factor='PASSCODE'
      < Content-Type: application/json
      < Transfer-Encoding: chunked
      < Date: Thu, 13 Mar 2XXX 21:10:50 GMT
      { [data not shown]
      100   186    0    96  100    90    159    149 --:--:-- --:--:-- --:--:--   159
      * Connection #0 to host identity.api.rackspacecloud.com/v2.0 left intact
      {
      "unauthorized": {
          "code": 401,
          "message": "Additional authentication credentials required."
          }
      }
          {
          "key":"value"
          } 

      To complete the authentication process, submit a second POST tokens authentication request that includes the sessionId and multi-factor authentication passcode from your phone:

      $curl https://identity.api.rackspacecloud.com/v2.0/tokens \
             -X POST \
             -d '{"auth": {"RAX-AUTH:passcodeCredentials": {"passcode":"1411594"}}}'\
             -H "X-SessionId: $SESSION_ID" \
             -H "Content-Type: application/json" --verbose -k

      The authentication response returns the authentication token ID and the service catalog with a list of available services. Save the token ID or export it to an environment variable to include in subsequent requests to Rackspace Cloud service API endpoints.

 Submit an API request to a Rackspace Cloud service

This procedure supplies a sample API request against the Rackspace Cloud Files service. You can submit API requests to any endpoint included in the service catalog returned in the authentication response body.

  1. Copy the token ID from the authentication response.

    You can export the value to an environment variable that can be supplied in the X-Auth-Token header for each API request.

  2. Use the service catalog returned in the authentication response to find URL for the API service that you want to use.

    For example, the endpoint for Cloud Files is https://storage101.ord1.clouddrive.com/v1/yourTenantID.

  3. Submit an API request to the API service endpoint.

    The following example shows a cURL request against the Cloud Files API to retrieve a list of CDN-enabled containers for the tenant.

    $ cURL -i -s \
    -X GET https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f \
    -H "X-Auth-Token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" \
    -H "Content-type: application/json"  --verbose -k

    The Cloud Files CDN 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: storage101.ord1.clouddrive.com
    > Accept: */*
    > X-Auth-Token: 69dc089d983f4729af29bec5a7dc6426
    > Content-type: application/json
    >
    < HTTP/1.1 200 OK
    HTTP/1.1 200 OK
    < Content-Length: 22
    Content-Length: 22
    < X-Account-Object-Count: 0
    X-Account-Object-Count: 0
    < X-Account-Storage-Policy-Policy-0-Bytes-Used: 0
    X-Account-Storage-Policy-Policy-0-Bytes-Used: 0
    < X-Timestamp: 1345588196.72805
    X-Timestamp: 1345588196.72805
    < X-Account-Storage-Policy-Policy-0-Object-Count: 0
    X-Account-Storage-Policy-Policy-0-Object-Count: 0
    < X-Account-Meta-Temp-Url-Key: e1f97840118eafc550d45dbd8e530c11
    X-Account-Meta-Temp-Url-Key: e1f97840118eafc550d45dbd8e530c11
    < X-Account-Bytes-Used: 0
    X-Account-Bytes-Used: 0
    < X-Account-Container-Count: 3
    X-Account-Container-Count: 3
    < Content-Type: text/plain; charset=utf-8
    Content-Type: text/plain; charset=utf-8
    < Accept-Ranges: bytes
    Accept-Ranges: bytes
    < X-Trans-Id: tx1353de66dd9d49da84eda-00544799f4ord1
    X-Trans-Id: tx1353de66dd9d49da84eda-00544799f4ord1
    < Date: Wed, 22 Oct 2014 11:50:12 GMT
    Date: Wed, 22 Oct 2014 11:50:12 GMT
    
    <
    metest
    mytest
    mytest2
    * Connection #0 to host storage101.ord1.clouddrive.com left intact
    
                    

 Manage authentication tokens

Authentication tokens are valid for 24 hours by default. You can find the expiration timestamp in the token object of the authentication response. If you re-authenticate before the token expires, the Identity service returns the same token as long as it remains valid.

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

When developing applications, make sure your code includes logic to cache tokens, check for expired tokens, and submit another authentciation request when required.

Identity administrators can use the Revoke token Identity API operation to delete an existing token if necessary.

 Learn more

Visit the following links to learn more about Rackspace Cloud Identity Service.

[Tip]Tip

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



loading table of contents...