Quick Start

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

To authenticate, submit a POST /v2.0/tokens request, presenting valid Rackspace service credentials in the message body to a Rackspace authentication endpoint. The authentication token is returned in response to a valid authentication request submitted with valid credentials. The response also returns a service catalog that lists the service endpoints that a user can access with the authentication token provided. After you have the authentication token, you can use it to submit API requests to the available endpoints.

Complete the following steps to authenticate to the Rackspace Cloud and submit API requests.

Step 1: Obtain an authentication token

  1. Get your Rackspace Cloud credentials.

    Credentials Type Description
    username and password xsd:string

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

    username and APIKey xsd:string

    You can get your API key from the Rackspace Cloud Control panel.

    1. Log into the Cloud Control panel.

    2. On the upper-right side of the top navigation pain, click your username.

    3. From the menu, select Account Settings.

    4. In the Login Details section of the Account Settings page, locate the API Key field and click Show.

    5. Copy the API key value and paste it into a text editor of your choice.

    6. Click Hide to hide the value of your API key.

    tenantId or tenantName(Optional) xsd:string

    Specify the tenantId or tenantName for the specified user account. Both the tenantId and tenantName are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.

    [Note]Note

    Administrative users can also authenticate by submittingtenantId and token credentials. For details, see Authenticate as tenant with token.

  2. Choose your authentication endpoint. You can use either of the following endpoints for authentication.

  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":"theUserName","apiKey":"thePassword"}}}' \
       -H "Content-type: application/json"

    Successful authentication returns a response with a token id that you can submit in the X-Auth-Token header of all Rackspace Cloud service API requests as evidence that your identity has already been authenticated, The response also provides a service catalog listing the available services that you can access with the token.

    [Note]Note

    If a user account is enabled for multi-factor authentication, an additional step is required to obtain the authentication token. For details, see Authenticate with multi-factor passcode credentials. Multi-factor authentication is only available to Rackspace customers in the Early Access program.

Step 2: Submit an API request to a Rackspace Cloud service

After you get an authentication token, you can use it to submit API requests to any of the services included in the Service catalog.

The following example shows a cURL request to get information about the Cloud Files service at endpoint https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee using the X-Auth-Token value to authenticate to the service.

$ curl https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee  \
-X GET \
-H 'X-Auth-Token:vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz' --verbose 

Step 3: Re-authenticate after the authentication token expires

An authentication token is valid for 24-hours, by default. The expiration date and time are provided in the token object of the authentication response.

When an authentication 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 Rackspace Cloud authentication endpoint.

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