Authenticate to the Rackspace Cloud#
Whether you use cURL, a REST client, or a command line client (CLI) to send requests
to the Rackspace RackConnect API, you need an authentication token to include in the X-Auth-Token
header of each API request.
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 developer documentation.
Authentication token operations
The examples in the Getting Started Guide show how to 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 authentication.
Follow these steps to authenticate to the Rackspace Cloud by using cURL.
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.
Note
For detailed information about the authentication response, see the annotated authentication request and response in the Rackspace Cloud API documentation.
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.
Note
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 Rackspace RackConnect 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-Tokenheader for each API request.The
expiresattribute 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. 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. 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 API_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
$API_ENDPOINT.
Note
The environment variables created with the export command are
valid only for the current terminal session. If you start a new session, run the
export commands again.
To reuse the variables across sessions, update the configuration file for your shell environment to include the export statements. For details about using and managing environment variables on different systems, see the Environment variables wiki.
Create environment variables
In the
tokensection of the authentication response, copy the tokenidand tenantidvalues 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" ] },
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
idvalue returned in the authentication response.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
idvalue returned in the authentication response.In the
service catalogsection of the authentication response, copy thepublicURLvalue for the Rackspace RackConnect API, version, and region that you want to access.Copy the URL, and then export it to an environment variable.
$ export API_ENDPOINT="publicURL"
Replace publicURL with the publicURL value listed in the service catalog.