Authenticate and save a session cookie for the RightScale API 1.5 in a file called 'mycookie' (http/curl), in memory (right_api_client) or 'cookieContainer' (Powershell). Authentication is required in order to run other examples scripts (and their API calls) elsewhere in this guide.

Note: Although OAuth is preferred for production environments, the Examples section of the API guide uses standard user/pass authentication for simplicity sake.

API Endpoints

IMPORTANT! Be sure to use the correct API endpoint in accordance with your account when using the API. Available values are:


You can check where the account is hosted from the URL while viewing the account. Examples in these docs use a variety of endpoints as examples only. If you get a HTTP 302 redirect, you are using a different API endpoint than the account is hosted.


The following uses curl/HTTP as part of a basic Unix shell script. Because several key variables are set in the script, you can literally copy, paste and change/set the variables in accord with your cloud assets to get you on your way using the RightScale API.

Example Call

    #!/bin/sh -e

    email=""    # The email address for your RightScale User in the Dashboard
    pswd="SomeSecurePassword"       # Your User's password
    account="1234"                  # Account ID, easily obtained from navigation in the Dashboard
    api_host="us-3"                 # Make sure to use the right API endpoint. Available values are: us-3, us-4 or telstra-10.

    curl -i -H X_API_VERSION:1.5 -c mycookie -X POST --data-urlencode "email=$email" --data-urlencode "password=$pswd" -d account_href=/api/accounts/"$account" https://$

Sample Output

    HTTP/1.1 204 No Content

    Server: nginx/1.0.15

    Date: Tue, 09 Oct 2012 22:11:46 GMT

    Connection: keep-alive

    Status: 204 No Content

    X-Runtime: 64

    X-Request-Uuid: 5687742b86ba40468c037d362d32a2db

    Set-Cookie: rs_gbl=eNo1kEFvgjABRv9Lz5DQFmxLsoMMMzQjgJls5NIoLaJTZFBENP338bDjl3zvHd4d5MAFpxEYQHbAvYO-Uy1wCaXkYQBdABdim1FkEWtmgL2czo5FFHVQbkLkKBNChUzh5M40McQS2jNpoUmn1T9L2Iud7KDe8yw3l7gRiUcallYRCajylzZbbaU_4pK06HipN_Pv3SEL9ej3PG2HehsK0ui0SpTXQ3Eakts2O8YyDrloEjivDhjhUovIG393s_nfZq2KevyJjvFw6egpjMmnuEVfI-02wWrRnlN9HeCHxRdBlrAd53VZeWvz3W76VO6L8zJgps_fXkWuryJ5UZz7WgOXORA-Hk9qR10P;; path=/; HttpOnly

    Set-Cookie: _session_id=e7ee4fd4bce4543a2b258b2c8d54db80; path=/; Secure; HttpOnly

    Cache-Control: no-cache

Successfully authenticating with the API always result in HTTP 204. The API session cookie will be saved to the file 'mycookie'. This cookie file contains the session ID for use with subsequent API calls used by the examples. The TTL (time to live) for the session cookie is 2 hours. An example cookie file looks similar to:

    $ cat mycookie # NOTE: Below cookie formatted slightly to make more readable.
    # Netscape HTTP Cookie File


    # This file was generated by libcurl! Edit at your own risk. TRUE / FALSE 0 rs_gbl eNo1kEFvgjAARv9Lz5DQFmxLsoMMMzQjgJls5WIoLaJTZFBFNP538bDjl3zvHd4d5MAFpxEYQHbAvYO-Uy1wCaXkYQBdABdim1FkEXtmgL2czo5FFHVQbkLkKBNChUzh5M40McQS2jNpoUmn1T9L2Iud7KDe8y



    fXkWuryJ5UZz7WgOWORA-Hk9qR10P FALSE / TRUE 0 _session_id e7ce4fb4bce4543b2b258b2c8d54db80

If your session cookie expires you will receive:

  • HTTP 403 Forbidden
  • Session cookie is expired or invalid message

If you get a 302 redirect, you are using a different API endpoint than the account is hosted. Use the correct API endpoint.


Important! Authentication works differently when using the right_api_client as opposed to the http/curl examples. Using standard authentication and the account facing RightScale API with http/curl requires authenticating whereby a session cookie is stored to a file. ('mycookie' in our examples.) The session cookie lasts for two hours, not requiring each subsequent API call to re-authenticate during that time. The authentication example below uses the right_api_client. Authentication information is stored as an object in memory. Hence, each Ruby script you develop and execute will require authenticating with the API.

Note : Technically speaking, although we refer to this simply as authentication, its really creating an object in the Ruby language so that one can use the RightScale API.


The authentication example below assumes the following Ruby and RightScale REST API client (right_api_client) installs have been completed.


To check that Ruby version 1.8.7 or later is installed.

    $ ruby -v

    ruby 1.8.7 (2011-06-30 patchlevel 352) [x86_64-linux]


Basic installation instructions for the RightScale REST API client (right_api_client).

    # sudo -i # switch to root user for installing the Ruby gem

    # gem install right_api_client

    Building native extensions. This could take a while...

    Successfully installed json-1.7.3

    Successfully installed mime-types-1.18

    Successfully installed rest-client-1.6.7

    Successfully installed right_api_client-1.5.9

    4 gems installed

    Installing ri documentation for json-1.7.3...

    Installing ri documentation for mime-types-1.18...

    Installing ri documentation for rest-client-1.6.7...

    Installing ri documentation for right_api_client-1.5.9...

    Installing RDoc documentation for json-1.7.3...

    Installing RDoc documentation for mime-types-1.18...

    Installing RDoc documentation for rest-client-1.6.7...

    Installing RDoc documentation for right_api_client-1.5.9...

    $ exit # logout from root user, create/run ruby scripts using right_api_client from a non-root user login.

Note : make sure you have the appropriate server permissions to perform these actions. For more information, see Server Login Control.

Example Call

    # Script: authenticate - Establish authentication with the RS API. Requires rubygems and right_api_client.

    # Authentication credentials stored in memory (not a cookie/file on local disk)

    require 'rubygems'

    require 'pp' # require the pp Pretty Print rubygem.

    require 'right_api_client'

    @client = => '', :password => 'SomeSecurePassword', :account_id => '1234')

    puts "Available methods: #{pp @client.api_methods}" # Use pretty print for more readable output

    #puts "Available methods: #{@client.api_methods}" # Use standard puts call. Less readable. Commented out so it will not be executed.

$ ruby authenticate # Run Ruby script 'authenticate' shown above.

Sample Output

Below output displays all methods available to the account that was previously authenticated. More information on each method is in the RightScale API 1.5 Online Reference.

Note : The following output uses pp (pretty print gem) in the Ruby script, producing more readable output. Future right_api_client examples will use pp instead of the standard Ruby puts call (which is shown below for contrast).
























Important! Only the resources (or their sub-resources) displayed in the output above can be used by the account. See the RightScale API Online Reference documentation for all API resources. Note that the resources for your account will likely vary somewhat.

Note : Below is sample output when using a Ruby puts call to display the available methods. The output is less readable, stringing together all methods on a single line with no delimeters or whitespace.

    Available methods: audit_entriesserverscloud_flow_processescloud_accountspublication_lineagesserver_template_multi_cloud_imagespermissionsdeploymentssecurity_group_rulesaccountspublicationsserver_templatesusersbackupscloudssessionalert_specstagsaccount_groupsserver_arrayschild_accountsidentity_providersmulti_cloud_images


Example Call

Note : See API Endpoints section for possible values to use in $postURL

    $email = "" # Use the Email Address for your RightScale User in the Dashboard

    $passwd = "SomeSecurePassword" # Your User's password

    $account = "1234" # Your RightScale Account ID, easily obtained via Dashboard navigation

    $postURL = ""

    $stringToPost = "email=$email&password=$passwd&account_href=/api/accounts/$account"

    $bytesToPost = [System.Text.Encoding]::UTF8.GetBytes($stringToPost)

    $cookieContainer = New-object System.Net.CookieContainer

    $webRequest = [System.Net.WebRequest]::Create($postURL)

    $webRequest.Method = "POST"

    $webRequest.ContentType = "application/x-www-form-urlencoded"


    $webRequest.ContentLength = $bytesToPost.Length

    $webRequest.PreAuthenticate = $false;

    $webRequest.ServicePoint.Expect100Continue = $false

    $webRequest.CookieContainer = $cookieContainer

    $requestStream = $webRequest.GetRequestStream()

    $requestStream.Write($bytesToPost, 0, $bytesToPost.Length)


    [System.Net.WebResponse]$response = $webRequest.GetResponse()

    $responseStream = $response.GetResponseStream()

    $responseStreamReader = New-Object System.IO.StreamReader -ArgumentList $responseStream

    [string]$responseString = $responseStreamReader.ReadToEnd()

    #this is the cookie container for subsequent requests: $cookieContainer

Sample Output

Same as http/curl response.