Authenticate to Rackspace

Whether you use cURL, a REST client, or a command-line client (CLI) to send requests to the Rackspace Ticketing API, you need an authentication token to include in the X-Auth-Token header of each request. To get a token, submit an authentication request with valid account credentials to the following Identity API service endpoint:

https://identity.api.rackspacecloud.com/v2.0

With a valid token, you can send API requests to any of the API service endpoints that you are authorized to use. The authentication response includes a token expiration date. When a token expires, you can send another authentication request to get a new one.

📘

Note

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

The examples in this API guide show how to authenticate by using username and API key credentials. Rackspace recommends this method of communicating with the API services. The authentication token operations reference in the Identity API documentation describes other types of credentials that you can use for authentication.

Authenticate by using cURL

Follow these steps to authenticate to the Rackspace Cloud by using cURL.

Important

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.

Send an authentication request

From a command prompt, send a POST tokens request to the Rackspace Cloud 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","api  
   Key":"$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 that you can access
  • user information and role assignments

Note

For detailed information about the authentication response, see the Annotated authentication request and response in the Rackspace Cloud API documentation.

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.

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, it returns the following values that you need to include when you make service requests to the Rackspace product API:

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 expires, unless it is revoked before 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. For Rackspace Cloud services, the tenant ID has the same value as the tenant name.

endpoint

The API endpoint provides the URL that you use to access the API service.

If the request failed, review the response message and the following error message descriptions to determine next steps.

  • If you see the following error message, review the authentication request for syntax or coding errors. If you are using cURL, see Using cURL.

    ❗️

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

    JSON formatting

  • If you see the following error message, verify the authentication credentials submitted in the authentication request. If necessary, contact your Rackspace Cloud Administrator or Rackspace Support to get valid credentials.

    ❗️

    401 Unable to authenticate user with credentials provided.

Note

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