Authenticate

Whether you use cURL or a REST client to send requests to the , you need to authenticate to the Rackspace Cloud. Cloud Feeds provides two methods to authenticate users:

Token-based authentication by using cURL

To make calls against the Cloud Feeds API by using an authentication token, you must first generate an authentication token. You provide this token in the X-Auth-Token header in each Cloud Feeds API request.

Follow these steps to use token-based authentication:

🚧

Warning

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.

πŸ“˜

Info

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

  • Authentication token operations

The examples in the Getting Started Guide show how to get an 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 token-based authentication.

  • Manage tokens and token expiration

Send an authentication request

From a command prompt, send a POST tokens request to the Identity service. Include your username and API key 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 you can access.
  • user information and role assignments

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.

πŸ“˜

Info

For a detailed description of the information included in the authentication response, see annotated authentication response.

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, you can find the authentication token and other information in the authentication response. You'll need these values to submit requests to the API. See Configure environment variables.

If the request failed, 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 the Using cURL.

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.

πŸ“˜

Info

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

Configure environment variables

The authentication response returns the following values that you need to include when you make service requests to the .

  • 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 prior to 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.

  • endpoint

    The endpoint provides the URL that you use to access the API service. For guidance on choosing an endpoint, see Service access.

To make it easier to include the 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.

Create environment variables

  1. In the token section of the authentication response, copy the token id and tenant id values from the token object.

    {
        "access": {
        "token": {
        "id": "AA2345631l1NVdD6D1OCauKA0e9fioquZqVlS-hpbCqQ5Yx1zLOREGf4efBh10CfB5AvjC1yld4ZNJUouE7DA0QB0n5nRbdDsYADA-ORICIqHNqOVS_kYmedqDh75c_PLe123456789101",
        "expires": "2015-11-18T18:35:45.013Z",
        "tenant": {
        "id": "123456",
        "name": "123456"
        },
        "RAX-AUTH:authenticatedBy": [
        "APIKEY"
        ]
    },
    
  2. 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.

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

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

    {
        "name": "cloudBigData",
        "endpoints": [
        {
        "region": "IAD",
        "tenantId": "123456",
        "publicURL": "https://iad.bigdata.api.rackspacecloud.com/v1.0/123456",
        "versionInfo": "httpis://iad.bigdata.api.rackspacecloud.com/v1.0",
        "versionList": "https://iad.bigdata.api.rackspacecloud.com/",
        "versionId": "1"
        },
        {
        "region": "DFW",
        "tenantId": "123456",
        "publicURL": "https://dfw.bigdata.api.rackspacecloud.com/v1.0/123456",
        "versionInfo": "https://dfw.bigdata.api.rackspacecloud.com/v1.0",
        "versionList": "https://dfw.bigdata.api.rackspacecloud.com/",
        "versionId": "1"
        },
        {
        "region": "IAD",
        "tenantId": "123456",
        "publicURL": "https://iad.bigdata.api.rackspacecloud.com/v2/123456",
        "versionInfo": "https://iad.bigdata.api.rackspacecloud.com/v2",
        "versionList": "https://iad.bigdata.api.rackspacecloud.com/",
        "versionId": "2"
        },
        {
        "region": "DFW",
        "tenantId": "123456",
        "publicURL": "https://dfw.bigdata.api.rackspacecloud.com/v2/123456",
        "versionInfo": "https://dfw.bigdata.api.rackspacecloud.com/v2",
        "versionList": "https://dfw.bigdata.api.rackspacecloud.com/",
        "versionId": "2"
        }
    ],
    "type": "rax:bigdata"
    },
    
  5. Copy the URL, and then export it to an environment variable.

    $ export ENDPOINT="publicURL"
    

    Replace publicURL with the publicURL value listed in the service catalog.

πŸ“˜

Info

The publicURL for consists of the service access endpoint URL to access the service with the tenant ID for your account appended.