Every REST request against the Rackspace Cloud Monitoring API requires the
inclusion of a specific authorization token, supplied by the
X-Auth-Token HTTP header. You obtain this token
by first using the Rackspace Cloud Identity Service and supplying a valid Rackspace account
username and API access key.
The Rackspace Cloud Identity Service serves as the entry point to all Rackspace Cloud APIs and is itself a RESTful web service. For a complete discussion of authentication, see Cloud Identity Client Developer Guide.
Multiple Rackspace Cloud Identity Service endpoints exist. When you authenticate, use the appropriate endpoint based on your account location:
| Account location | Rackspace Cloud Identity Service endpoint |
|---|---|
| US-based account | https://identity.api.rackspacecloud.com/v2.0 |
| UK-based account | https://lon.identity.api.rackspacecloud.com/v2.0 |
For information about support for legacy identity endpoints, see Alternate Authentication Endpoints.
| Verb | URI | Description | |||
| POST | /auth | Authenticate to receive a token and a service catalog. | |||
Normal Response Code(s): 200, 203
Error Response Code(s): unauthorized (401), userDisabled (403), badRequest (400), authFault (500), serviceUnavailable (503)
The authenticate operation provides clients with an authentication token and a list of regional cloud endpoints.
The username supplied here is your common Rackspace Cloud username.
The key is your API access key. To obtain your API key, log into https://mycloud.rackspace.com, click your username, and select API Keys to get your key.
Example 3.1. Auth Request: XML
<?xml version="1.0" encoding="UTF-8"?>; <auth>; <apiKeyCredentials xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0" username="MyRackspaceAcct" apiKey="0000000000000000000"/>;
</auth>;
Example 3.2. Auth Request: JSON
{
"auth":{
"RAX-KSKEY:apiKeyCredentials":{
"username":"MyRackspaceAcct",
"apiKey":"0000000000000000000"
}
}
}
Example 3.3. Auth Response: XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<access
xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
xmlns="http://docs.openstack.org/identity/api/v2.0">
<token id="5384dae4-e32e-40b1-a8ec-bc84135434c5"
expires="2012-09-18T20:20:55.000-05:00">
<tenant id="010101" name="010101"/>
</token>
<user
xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
id="172157" name="MyRackspaceAcct"
rax-auth:defaultRegion="DFW">
<roles>
<role id="3" name="identity:user-admin"
description="User Admin Role."/>
</roles>
</user>
<serviceCatalog>
<service type="rax:object-cdn" name="cloudFilesCDN">
<endpoint region="DFW"
tenantId="MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
/>
</service>
<service type="object-store" name="cloudFiles">
<endpoint region="DFW"
tenantId="MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
publicURL="https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
internalURL="https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
publicURL="https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
internalURL="https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
/>
</service>
<service type="compute" name="cloudServers">
<endpoint tenantId="010101"
publicURL="https://servers.api.rackspacecloud.com/v1.0/010101">
<version id="1.0"
info="https://servers.api.rackspacecloud.com/v1.0"
list="https://servers.api.rackspacecloud.com/"/>
</endpoint>
</service>
<service type="rax:dns" name="cloudDNS">
<endpoint tenantId="010101"
publicURL="https://dns.api.rackspacecloud.com/v1.0/010101"
/>
</service>
<service type="compute" name="cloudServersOpenStack">
<endpoint region="ORD" tenantId="010101"
publicURL="https://ord.servers.api.rackspacecloud.com/v2/010101">
<version id="2"
info="https://ord.servers.api.rackspacecloud.com/v2"
list="https://ord.servers.api.rackspacecloud.com/"
/>
</endpoint>
<endpoint region="DFW" tenantId="010101"
publicURL="https://dfw.servers.api.rackspacecloud.com/v2/010101">
<version id="2"
info="https://dfw.servers.api.rackspacecloud.com/v2"
list="https://dfw.servers.api.rackspacecloud.com/"
/>
</endpoint>
</service>
<service type="rax:database" name="cloudDatabases">
<endpoint region="DFW" tenantId="010101"
publicURL="https://dfw.databases.api.rackspacecloud.com/v1.0/010101"/>
<endpoint region="ORD" tenantId="010101"
publicURL="https://ord.databases.api.rackspacecloud.com/v1.0/010101"
/>
</service>
<service type="rax:load-balancer" name="cloudLoadBalancers">
<endpoint region="ORD" tenantId="010101"
publicURL="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/010101"/>
<endpoint region="DFW" tenantId="010101"
publicURL="https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/010101"
/>
</service>
<service type="rax:monitor" name="cloudMonitoring">
<endpoint tenantId="010101"
publicURL="https://monitoring.api.rackspacecloud.com/v1.0/010101"
/>
</service>
</serviceCatalog>
</access>
Example 3.4. Auth Response: JSON
{
"access": {
"serviceCatalog": [
{
"endpoints": [
{
"publicURL": "https://servers.api.rackspacecloud.com/v1.0/010101",
"tenantId": "010101",
"versionId": "1.0",
"versionInfo": "https://servers.api.rackspacecloud.com/v1.0",
"versionList": "https://servers.api.rackspacecloud.com/"
}
],
"name": "cloudServers",
"type": "compute"
},
{
"endpoints": [
{
"internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f",
"publicURL": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f",
"region": "DFW",
"tenantId": "MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
},
{
"internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f",
"publicURL": "https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f",
"region": "ORD",
"tenantId": "MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
}
],
"name": "cloudFiles",
"type": "object-store"
},
{
"endpoints": [
{
"publicURL": "https://cdn1.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f",
"region": "DFW",
"tenantId": "MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
},
{
"publicURL": "https://cdn2.clouddrive.com/v1/MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f",
"region": "ORD",
"tenantId": "MossoCloudFS_9c24e3db-52bf-4f26-8dc1-220871796e9f"
}
],
"name": "cloudFilesCDN",
"type": "rax:object-cdn"
},
{
"endpoints": [
{
"publicURL": "https://ord.servers.api.rackspacecloud.com/v2/010101",
"region": "ORD",
"tenantId": "010101",
"versionId": "2",
"versionInfo": "https://ord.servers.api.rackspacecloud.com/v2",
"versionList": "https://ord.servers.api.rackspacecloud.com/"
},
{
"publicURL": "https://dfw.servers.api.rackspacecloud.com/v2/010101",
"region": "DFW",
"tenantId": "010101",
"versionId": "2",
"versionInfo": "https://dfw.servers.api.rackspacecloud.com/v2",
"versionList": "https://dfw.servers.api.rackspacecloud.com/"
}
],
"name": "cloudServersOpenStack",
"type": "compute"
},
{
"endpoints": [
{
"publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/010101",
"region": "ORD",
"tenantId": "010101"
},
{
"publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/010101",
"region": "DFW",
"tenantId": "010101"
}
],
"name": "cloudLoadBalancers",
"type": "rax:load-balancer"
},
{
"endpoints": [
{
"publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/010101",
"region": "ORD",
"tenantId": "010101"
},
{
"publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/010101",
"region": "DFW",
"tenantId": "010101"
}
],
"name": "cloudDatabases",
"type": "rax:database"
},
{
"endpoints": [
{
"publicURL": "https://monitoring.api.rackspacecloud.com/v1.0/010101",
"tenantId": "010101"
}
],
"name": "cloudMonitoring",
"type": "rax:monitor"
},
{
"endpoints": [
{
"publicURL": "https://dns.api.rackspacecloud.com/v1.0/010101",
"tenantId": "010101"
}
],
"name": "cloudDNS",
"type": "rax:dns"
}
],
"token": {
"expires": "2012-09-18T20:20:55.000-05:00",
"id": "5384dae4-e32e-40b1-a8ec-bc84135434c5",
"tenant": {
"id": "010101",
"name": "010101"
}
},
"user": {
"RAX-AUTH:defaultRegion": "DFW",
"id": "172157",
"name": "MyRackspaceAcct",
"roles": [
{
"description": "User Admin Role.",
"id": "3",
"name": "identity:user-admin"
}
]
}
}
}
The authentication response contains the following information:
token idSpecifies the authentication token. Tokens are valid for a finite duration; a token's default lifespan is twenty-four hours.
expiresDenotes the time after which the token will automatically become invalid. A token may be manually revoked before the time identified by the
expiresattribute; this attribute predicts a token's maximum possible lifespan but does not guarantee that it will reach that lifespan. Clients are encouraged to cache a token until it expires.serviceCatalogLists the regions and public and private URLs for each of the Rackspace products and services you have access to.
publicURLLists the public URL for each product and service.
![[Note]](/cm-v1.0-cm-devguide/common/images/admon/note.png)
Note You will find your account number after the final '/' in the
publicURLfield. In this example the account number is 010101.
While an authentication token lasts, you can continue to
perform requests. When a token expires, it returns an HTTP
error code 401 Unauthorized. Given that an
X-Auth-Token is good for 24 hours, long-running
or high-request-rate jobs should not try to authenticate at a
Rackspace Cloud Identity Service endpoint on every request. You don't need to request
another X-Auth-Token again until your existing
X-Auth-Token expires. At that point you must
obtain another authorization token. Here is a best-practice
example of a scalable process flow :
Begin requests by going to the Rackspace Cloud Identity Service endpoint for your location for an
X-Auth-Token. See Section 3.1.1, “Rackspace Cloud Identity Service Endpoints”.Send request X-Storage-URL using the
X-Auth-Tokenobtained in Step 1.Repeat Step 2 using the same
X-Auth-Tokenretrieved in Step 1 until either the job finishes or you get a result code of 401 (Unauthorized).If the job finishes, you can allow the token to expire with no further action.
If result code is 401, send a request to the Rackspace Cloud Identity Service endpoint for a new
X-Auth-Token.
