Cloud Management API 1.5

Sessions

The sessions resource is in charge of creating API sessions that are bound to a given account. The sequence for login into the API is the following: * Perform a POST request to /api/sessions ('create' action) to my.rightscale.com or to any more specific hosts saved from previous sessions. * If the targeted host is not appropriate for the specific account being accessed it will return a 302 http code with a URL with which the client must retry the same POST request. * If the targeted host is the right one and the login is successful, it will return a 204 http code, along with two cookies that will need to be saved and passed in any subsequent API request. * If there is an authentication or authorization problem with the POST request an error (typically 401 or 422 ) may be returned at any point in the above sequence. * If the session expires, it will return a 403 http code with a "Session cookie is expired or invalid" message.

Note that all API calls irrespective of the resource it is acting on, should pass a header "X_API_VERSION" with the value "1.5".

index

Returns a list of root resources so an authenticated session can use them as a starting point or a way to know what features are available within its privileges.

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -b mycookies -X GET https://my.rightscale.com/api/sessions

URLs: GET /api/session [DEPRECATED]; GET /api/sessions
HTTP response code: 200 OK
Content-type: application/vnd.rightscale.session

Required roles

observer

Parameters

name	required	type	values	regexp	blank?	description
view	no	String	default, whoami	*	no	Whoami view provides links to the logged-in principal and the account being accessed

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML

{
  "actions": [

  ],
  "message": "You have successfully logged into the RightScale API.",
  "links": [
    {"rel":"account_groups","href":"/api/account_groups"},
    {"rel":"accounts","href":"/api/accounts"},
    {"rel":"alert_specs","href":"/api/alert_specs"},
    {"rel":"alerts","href":"/api/alerts"},
    {"rel":"audit_entries","href":"/api/audit_entries"},
    {"rel":"backups","href":"/api/backups"},
    {"rel":"child_accounts","href":"/api/child_accounts"},
    {"rel":"cloud_accounts","href":"/api/cloud_accounts"},
    {"rel":"clouds","href":"/api/clouds"},
    {"rel":"cookbooks","href":"/api/cookbooks"},
    {"rel":"credentials","href":"/api/credentials"},
    {"rel":"deployments","href":"/api/deployments"},
    {"rel":"identity_providers","href":"/api/identity_providers"},
    {"rel":"multi_cloud_images","href":"/api/multi_cloud_images"},
    {"rel":"network_gateways","href":"/api/network_gateways"},
    {"rel":"network_option_group_attachments","href":"/api/network_option_group_attachments"},
    {"rel":"network_option_groups","href":"/api/network_option_groups"},
    {"rel":"networks","href":"/api/networks"},
    {"rel":"permissions","href":"/api/permissions"},
    {"rel":"placement_groups","href":"/api/placement_groups"},
    {"rel":"preferences","href":"/api/preferences"},
    {"rel":"publication_lineages","href":"/api/publication_lineages"},
    {"rel":"publications","href":"/api/publications"},
    {"rel":"repositories","href":"/api/repositories"},
    {"rel":"right_scripts","href":"/api/right_scripts"},
    {"rel":"route_tables","href":"/api/route_tables"},
    {"rel":"routes","href":"/api/routes"},
    {"rel":"security_group_rules","href":"/api/security_group_rules"},
    {"rel":"self","href":"/api/session"},
    {"rel":"server_arrays","href":"/api/server_arrays"},
    {"rel":"server_template_multi_cloud_images","href":"/api/server_template_multi_cloud_images"},
    {"rel":"server_templates","href":"/api/server_templates"},
    {"rel":"servers","href":"/api/servers"},
    {"rel":"tags","href":"/api/tags"},
    {"rel":"users","href":"/api/users"}
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<session>
  <actions/>
  <message>You have successfully logged into the RightScale API.</message>
  <links>
    <link rel="account_groups" href="/api/account_groups"/>
    <link rel="accounts" href="/api/accounts"/>
    <link rel="alert_specs" href="/api/alert_specs"/>
    <link rel="alerts" href="/api/alerts"/>
    <link rel="audit_entries" href="/api/audit_entries"/>
    <link rel="backups" href="/api/backups"/>
    <link rel="child_accounts" href="/api/child_accounts"/>
    <link rel="cloud_accounts" href="/api/cloud_accounts"/>
    <link rel="clouds" href="/api/clouds"/>
    <link rel="cookbooks" href="/api/cookbooks"/>
    <link rel="credentials" href="/api/credentials"/>
    <link rel="deployments" href="/api/deployments"/>
    <link rel="identity_providers" href="/api/identity_providers"/>
    <link rel="multi_cloud_images" href="/api/multi_cloud_images"/>
    <link rel="network_gateways" href="/api/network_gateways"/>
    <link rel="network_option_group_attachments" href="/api/network_option_group_attachments"/>
    <link rel="network_option_groups" href="/api/network_option_groups"/>
    <link rel="networks" href="/api/networks"/>
    <link rel="permissions" href="/api/permissions"/>
    <link rel="placement_groups" href="/api/placement_groups"/>
    <link rel="preferences" href="/api/preferences"/>
    <link rel="publication_lineages" href="/api/publication_lineages"/>
    <link rel="publications" href="/api/publications"/>
    <link rel="repositories" href="/api/repositories"/>
    <link rel="right_scripts" href="/api/right_scripts"/>
    <link rel="route_tables" href="/api/route_tables"/>
    <link rel="routes" href="/api/routes"/>
    <link rel="security_group_rules" href="/api/security_group_rules"/>
    <link rel="self" href="/api/session"/>
    <link rel="server_arrays" href="/api/server_arrays"/>
    <link rel="server_template_multi_cloud_images" href="/api/server_template_multi_cloud_images"/>
    <link rel="server_templates" href="/api/server_templates"/>
    <link rel="servers" href="/api/servers"/>
    <link rel="tags" href="/api/tags"/>
    <link rel="users" href="/api/users"/>
  </links>
</session>

Click on a format below to see an example response for the 'whoami' view:

JSON XML

{
  "actions": [

  ],
  "message": "You have successfully logged into the RightScale API.",
  "links": [
    {"rel":"account","href":"/api/accounts/560182816"},
    {"rel":"user","href":"/api/users/560368754"}
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<session>
  <actions/>
  <message>You have successfully logged into the RightScale API.</message>
  <links>
    <link rel="account" href="/api/accounts/560182816"/>
    <link rel="user" href="/api/users/560368754"/>
  </links>
</session>

create

Creates API session scoped to a given account. (API login)

This call requires a form of authentication (user and password), as well as the account for which the session needs to be created. Upon successfully authenticating the credentials, the system will return a 204 code and set of two cookies that will serve as the credentials for the session. Both of these cookies must be passed in any of the subsequent requests for this session. If an 302 redirect code is returned, the client is responsible of re-issuing the POST request against the content of the received Location header, passing the exact same parameters again.

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -c mycookies -X POST -d email='email@me.com' -d password='mypassword' -d account_href=/api/accounts/11 https://my.rightscale.com/api/sessions

URLs: POST /api/session [DEPRECATED]; POST /api/sessions
HTTP response code: 204 No Content

Parameters

name	required	type	values	regexp	blank?	description
account_href	yes	String	*	^/api/accounts/\d+$	no	The account href for which the session needs to be created.
email	yes	String	*	*	no	The email to login with.
password	yes	String	*	*	no	The corresponding password.

accounts

List all the accounts that a user has access to.

This call may be executed outside of an existing session. Doing so requires passing a username and password in the request body. The idea is that it should be possible to list accounts that can be used to create a session.

Upon successfully authenticating the credentials, the system will return a 200 OK code and return the list of accounts. If an 302 redirect code is returned, the client is responsible of re-issuing the GET request against the content of the received Location header, passing the exact same parameters again.

Example Request using Curl (not using an existing session):
curl -i -H X_API_VERSION:1.5 -X GET -d email='email@me.com' -d password='mypassword' https://my.rightscale.com/api/sessions/accounts

Example Request using Curl (using an existing session):
curl -i -H X_API_VERSION:1.5 -X GET -b mycookies https://my.rightscale.com/api/sessions/accounts

URLs: GET /api/session/accounts; GET /api/sessions/accounts
HTTP response code: 200 OK
Content-type: application/vnd.rightscale.account;type=collection

Parameters

name	required	type	values	regexp	blank?	description
email	no	String	*	*	no	The email to login with if not using existing session.
password	no	String	*	*	no	The corresponding password.
view	no	String	default, extended	*	no	Extended view shows account permissions and products

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML

[{
  "name": "SPEC_ACCOUNT",
  "created_at": "2023/10/09 11:06:00 +0000",
  "updated_at": "2023/10/09 11:06:00 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/560182816"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ]
},{
  "name": "SPEC_ACCOUNT",
  "created_at": "2023/10/09 11:06:00 +0000",
  "updated_at": "2023/10/09 11:06:00 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/560182816"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ]
}]

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2023/10/09 11:06:00 +0000</created_at>
    <updated_at>2023/10/09 11:06:00 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/560182816"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
  </account>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2023/10/09 11:06:00 +0000</created_at>
    <updated_at>2023/10/09 11:06:00 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/560182816"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
  </account>
</accounts>

Click on a format below to see an example response for the 'extended' view:

JSON XML

[{
  "name": "SPEC_ACCOUNT",
  "created_at": "2023/10/09 11:06:00 +0000",
  "updated_at": "2023/10/09 11:06:00 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/560182816"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ],
  "products": [

  ],
  "permissions": [

  ]
},{
  "name": "SPEC_ACCOUNT",
  "created_at": "2023/10/09 11:06:00 +0000",
  "updated_at": "2023/10/09 11:06:00 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/560182816"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ],
  "products": [

  ],
  "permissions": [

  ]
}]

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2023/10/09 11:06:00 +0000</created_at>
    <updated_at>2023/10/09 11:06:00 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/560182816"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
    <products/>
    <permissions/>
  </account>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2023/10/09 11:06:00 +0000</created_at>
    <updated_at>2023/10/09 11:06:00 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/560182816"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
    <products/>
    <permissions/>
  </account>
</accounts>

create_instance_session

Creates API session scoped to a given account and instance.

This call requires a form of authentication (token), as well as the account for which the session needs to be created. Upon successfully authenticating the credentials, the system will return a 204 code and set of two cookies that will serve as the credentials for the session. Both of these cookies must be passed in any of the subsequent requests for this session. If an 302 redirect code is returned, the client is responsible of re-issuing the POST request against the content of the received Location header, passing the exact same parameters again.

Users can find their account ID and instance\_token from their instance's user_data:
account ID regex: /RS_API_TOKEN=(\d+):/
instance_token regex: /RS_API_TOKEN=(?:\d+):(\w+)&/

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -c mycookies -X POST -d instance_token='randomtoken' -d account_href=/api/accounts/11 https://my.rightscale.com/api/sessions/instance

URLs: POST /api/session/instance; POST /api/sessions/instance
HTTP response code: 204 No Content

Parameters

name	required	type	values	regexp	blank?	description
account_href	yes	String	*	^/api/accounts/\d+$	no	The account href for which the session needs to be created.
instance_token	yes	String	*	*	no	The instance token to login with.

index_instance_session

Shows the full attributes of the instance (that has the token used to log-in). This call can be used by an instance to get it's own details.

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -b mycookies -X GET https://my.rightscale.com/api/sessions/instance

URLs: GET /api/session/instance; GET /api/sessions/instance
HTTP response code: 200 OK
Content-type: application/vnd.rightscale.instance

Required roles

instance

Example Responses

Click on a format below to see an example response:

JSON XML

{
  "name": "NAME_409940392",
  "created_at": "2023/10/09 11:06:01 +0000",
  "updated_at": "2023/10/09 11:06:01 +0000",
  "resource_uid": "RESOURCE_2014175382",
  "links": [
    {"rel":"self","href":"/api/clouds/888/instances/RESOURCE_2014175382;RAND"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"deployment","href":"/api/deployments/2"},
    {"rel":"server_template","href":"/api/server_templates/1"},
    {"rel":"multi_cloud_image","href":"/api/multi_cloud_images/1","inherited_source":"server_template"},
    {"rel":"parent","href":"/api/servers/1"},
    {"rel":"volume_attachments","href":"/api/clouds/888/instances/RESOURCE_2014175382;RAND/volume_attachments"},
    {"rel":"inputs","href":"/api/clouds/888/instances/RESOURCE_2014175382;RAND/inputs"},
    {"rel":"monitoring_metrics","href":"/api/clouds/888/instances/RESOURCE_2014175382;RAND/monitoring_metrics"},
    {"rel":"alerts","href":"/api/clouds/888/instances/RESOURCE_2014175382;RAND/alerts"},
    {"rel":"alert_specs","href":"/api/clouds/888/instances/RESOURCE_2014175382;RAND/alert_specs"}
  ],
  "cloud_specific_attributes": {
  },
  "associate_public_ip_address": true,
  "actions": [
    {
      "rel": "terminate"
    },
    {
      "rel": "reboot"
    },
    {
      "rel": "run_executable"
    },
    {
      "rel": "lock"
    },
    {
      "rel": "unlock"
    }
  ],
  "public_ip_addresses": [
    "184.9.35.124"
  ],
  "private_ip_addresses": [
    "9.6.9.2"
  ],
  "pricing_type": "fixed",
  "locked": false,
  "state": "operational"
}

<?xml version="1.0" encoding="UTF-8"?>
<instance>
  <name>NAME_409940392</name>
  <created_at>2023/10/09 11:06:01 +0000</created_at>
  <updated_at>2023/10/09 11:06:01 +0000</updated_at>
  <resource_uid>RESOURCE_2014175382</resource_uid>
  <links>
    <link rel="self" href="/api/clouds/888/instances/RESOURCE_2014175382;RAND"/>
    <link rel="cloud" href="/api/clouds/888"/>
    <link rel="deployment" href="/api/deployments/2"/>
    <link rel="server_template" href="/api/server_templates/1"/>
    <link rel="multi_cloud_image" href="/api/multi_cloud_images/1" inherited_source="server_template"/>
    <link rel="parent" href="/api/servers/1"/>
    <link rel="volume_attachments" href="/api/clouds/888/instances/RESOURCE_2014175382;RAND/volume_attachments"/>
    <link rel="inputs" href="/api/clouds/888/instances/RESOURCE_2014175382;RAND/inputs"/>
    <link rel="monitoring_metrics" href="/api/clouds/888/instances/RESOURCE_2014175382;RAND/monitoring_metrics"/>
    <link rel="alerts" href="/api/clouds/888/instances/RESOURCE_2014175382;RAND/alerts"/>
    <link rel="alert_specs" href="/api/clouds/888/instances/RESOURCE_2014175382;RAND/alert_specs"/>
  </links>
  <cloud_specific_attributes/>
  <associate_public_ip_address>true</associate_public_ip_address>
  <actions>
    <action rel="terminate"/>
    <action rel="reboot"/>
    <action rel="run_executable"/>
    <action rel="lock"/>
    <action rel="unlock"/>
  </actions>
  <public_ip_addresses>
    <public_ip_address>184.9.35.124</public_ip_address>
  </public_ip_addresses>
  <private_ip_addresses>
    <private_ip_address>9.6.9.2</private_ip_address>
  </private_ip_addresses>
  <pricing_type>fixed</pricing_type>
  <locked>false</locked>
  <state>operational</state>
</instance>

MediaTypes:

Resources:

Sessions

Actions

index

Required roles

Parameters

Example Responses

Click on a format below to see an example response for the 'default' view:

Click on a format below to see an example response for the 'whoami' view:

create

Parameters

accounts

Parameters

Example Responses

Click on a format below to see an example response for the 'default' view:

Click on a format below to see an example response for the 'extended' view:

create_instance_session

Parameters

index_instance_session

Required roles

Example Responses

Click on a format below to see an example response: