• Buy Now
    • Rackspace Cloud
    • Email & Apps
    • Fanatical Support for AWS
    • Managed Google Cloud Platform
    • Office 365
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Cloud Office Control Panel
  • Rackspace Logo
  • Developer Home
  • Developer Documentation
  • Blogs ▼
    • Technical Blog
    • Rackspace Blog
    • Solve: Thought Leadership
  • Support Documentation

Developer Docs


Let’s Build Something Powerful Together!

End-to-End Multicloud Solutions.   Solving Together.™   Learn more at Rackspace.com

Submit an issue
  • Cloud Networks 2.0
  • Getting started
    • Get your credentials
    • Send API requests to Rackspace Cloud Networks
      • Install CLI clients and Cloud Networks Virtual Interface extension
      • Convert cURL examples to run on Windows
    • Authenticate to the Rackspace Cloud
      • Authenticate by using the nova client
      • Authenticate by using cURL
      • Send an authentication request
      • Review the authentication response
      • Configure environment variables
    • Rackspace Cloud Networks Concepts
      • Network concepts
      • Subnet concepts
      • Port concepts
      • Security groups and rules concepts
      • Shared IP addresses
    • Manage networks
      • Creating and listing networks
      • Booting a new server
      • Deleting a network
      • Attaching a network to an existing server
    • Configure network variations
      • Controlling dynamic IP address allocation by using allocation pools
      • Configuring host routes
      • Provisioning IP addresses on isolated network ports
      • Sharing IP addresses
    • Control network access
      • Controlling network traffic
  • General API Information
    • Service access endpoints
    • Request and response types
    • Paginated collections
    • Quotas
    • Filtering requests
    • Date and time format
    • Role Based Access Control
      • Assigning roles to account users
      • Roles available for Cloud Networks
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC permissions cross-reference to Cloud Networks API operations
  • API reference
    • Network operations
      • Retrieve list of networks
      • Create network
      • Show network
      • Update network
      • Delete network
    • Subnet operations
      • Retrieve list of subnets
      • Create subnet
      • Show subnet
      • Update subnet
      • Delete subnet
    • Port operations
      • Retrieve list of ports
      • Create port
      • Show port
      • Update port
      • Delete port
    • Security groups operations
      • List security groups
      • Create security group
      • Show security group
      • Delete security group
      • List security group rules
      • Create security group rule
      • Show security group rule
      • Delete security group rule
    • Shared IP address operations
      • Retrieve list of IP addresses
      • Provision IP address
      • Update ports with an IP address
      • Show IP address details
      • De-allocate IP address
      • Retrieve list of IP addresses explicitly associated with a server
      • Explicitly associate IP address with server
      • Show specific IP addresses explicitly associated with server
      • Delete association between IP address and server
  • Release Notes
    • API v2.0 updates, February 07, 2017
      • What's new
      • Resolved issues
      • Known issues
    • API v2.0 updates, August 15, 2016
      • What's new
      • Resolved issues
      • Known issues
    • API v2.0 updates, July 25, 2016
      • What's new
      • Resolved issues
      • Known issues
    • API v2.0 updates, March 24, 2015
      • What's new
      • Resolved issues
      • Known issues
    • API v2.0 updates, March 19, 2015
      • What's new
      • Resolved issues
      • Known issues
    • API v2.0 release, September 30, 2014
      • What's new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

Authenticate to the Rackspace Cloud#

Whether you use cURL, a REST client, or a command-line client (CLI) to send requests to the Rackspace Cloud Networks API, you need an authentication token to include in the X-Auth-Token header of each request. You get a token by submitting 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:

  • Authentication token operations

    The examples in this API 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 in the Identity API documentation describes other types of credentials that you can use for authentication.

  • Manage authentication tokens

To start using the API and run the examples in this section, you need the following items:

  • Rackspace Cloud account. If you don't have an account, sign up for one.
  • Command-line tool or browser client for communicating with the API service.

Authenticate by using the nova client#

Use the following steps to authenticate by using the nova client to get the authentication token and the service catalog:

  1. Get an authentication token:

    $ nova credentials
    

    Successful authentication returns user credentials, including ID, name, roles, and the authentication token. The token appears in the id field in the Token box as shown in the following example.

    +------------------+---------------------------------------------------------------------------------------+
    | User Credentials | Value                                                                                 |
    +------------------+---------------------------------------------------------------------------------------+
    | id               | 170454                                                                                |
    | name             | MyRackspaceAcct                                                                       |
    | roles            | [{u'description': u'User Admin Role.', u'id': u'3', u'name': u'identity:user-admin'}] |
    +------------------+---------------------------------------------------------------------------------------+
    +---------+----------------------------------------+
    | Token   | Value                                  |
    +---------+----------------------------------------+
    | expires | 2012-07-28T13:58:56.000-05:00          |
    | id      | 1bd336d5-e0c6-49d9-b902-d3dbdc463062   |
    | tenant  | {u'id': u'010101', u'name': u'010101'} |
    +---------+----------------------------------------+
    

    After you generate a token, the nova client automatically injects the token into any nova client commands that you issue.

    However, because the token expires after 24 hours, you must generate a new token once a day.

  2. Get the service catalog with a list of endpoints:

    $ nova endpoints
    

    For each service, the response includes the public URL (which is the endpoint, including your tenant ID, that you use to access the service), the region, the service name, the tenant ID, the version ID, and the endpoints that you can use to get version information for the API.

    To access the Cloud Networks or next generation Cloud Servers service, use the publicURL value for the cloudServersOpenStack service.

    The following example shows the information returned for the DFW region for the Cloud Servers service:

    +-----------------------+------------------------------------------------------+
    | cloudServersOpenStack | Value                                                |
    +-----------------------+------------------------------------------------------+
    | publicURL             | https://dfw.servers.api.rackspacecloud.com/v2/010101 |
    | region                | DFW                                                  |
    | serviceName           | cloudServersOpenStack                                |
    | tenantId              | 010101                                               |
    | versionId             | 2                                                    |
    | versionInfo           | https://dfw.servers.api.rackspacecloud.com/v2        |
    | versionList           | https://dfw.servers.api.rackspacecloud.com/          |
    +-----------------------+------------------------------------------------------+
    

    The cloudServersOpenStack service might show multiple endpoints to enable regional choice. Select the appropriate endpoint for the region that you want to interact with by examining the region field.

  3. Copy the values in the publicURL and tenantId fields for the cloudServersOpenStack service for your region.

Authenticate by using cURL#

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

  • Send an authentication request
  • Review the authentication response
  • Configure environment variables

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","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 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 will expire, unless it is revoked before the expiration. To get a new token, submit another authentication request. For more information, see Manage authentication tokens.

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.

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.

Configure environment variables#

To make it easier to include the token ID, tenant ID, endpoint, and other 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.

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

  1. In the token section of the authentication response, copy the token id and tenant id values from the token object. The following example shows example values only.

    {
    "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 Rackspace Cloud Networks API, version, and region that you want to access.

    This example shows the endpoints available for the Rackspace Cloud Networks API.

    {
          "name": "cloudNetworks",
          "endpoints": [
              {
                  "region": "IAD",
                  "tenantId": "661145",
                  "publicURL": "https://iad.networks.api.rackspacecloud.com/v2.0"
              },
              {
                  "region": "LON",
                  "tenantId": "661145",
                  "publicURL": "https://lon.networks.api.rackspacecloud.com/v2.0"
              },
              {
                  "region": "ORD",
                  "tenantId": "661145",
                  "publicURL": "https://ord.networks.api.rackspacecloud.com/v2.0"
              },
              {
                  "region": "SYD",
                  "tenantId": "661145",
                  "publicURL": "https://syd.networks.api.rackspacecloud.com/v2.0"
              },
              {
                  "region": "DFW",
                  "tenantId": "661145",
                  "publicURL": "https://dfw.networks.api.rackspacecloud.com/v2.0"
              },
              {
                  "region": "HKG",
                  "tenantId": "661145",
                  "publicURL": "https://hkg.networks.api.rackspacecloud.com/v2.0"
              }
          ],
          "type": "network"
      },
    

    Note

    For some services, the publicURL value for the API consists of the endpoint URL with the tenant ID for your account appended after the final /.

  5. Export the URL to an environment variable, as shown in the following example:

    $ export API_ENDPOINT="publicURL"
    

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

Previous Send API requests to Rackspace Cloud Networks
Next Rackspace Cloud Networks Concepts
Developer Network
  • Developer Center
  • API Documentation and User Guides
  • SDKs
  • Rackspace How-To
Blogs
  • Technical Blog
  • Rackspace Blog
  • Solve: Thought Leadership
Other Information
  • Customer Stories
  • Events
  • Programs
  • Careers
  • Style Guide for Technical Content
©2020 Rackspace US, Inc.
  • ©2020 Rackspace US, Inc.
  • About Rackspace
  • Privacy Statement
  • Website Terms
  • Trademarks