OpenStack API Complete Reference

Use the OpenStack APIs and extensions to launch server instances, create images, assign metadata to instances and images, create containers and objects, and complete other actions in your OpenStack cloud.

The API status reflects the state of the endpoint on the service. CURRENT is a stable version that is up-to-date, recent, and might receive future versions. This endpoint should be prioritized over all others. SUPPORTED is a stable version that is available on the server. However, it is not likely the most recent available and might not be updated or might be deprecated at some time in the future. DEPRECATED is a stable version that is still available but is being deprecated and might be removed in the future. EXPERIMENTAL is not a stable version. This version is under development or contains features that are otherwise subject to change. For more information about API status values and version information, see Version Discovery.

You must install the packages for each API separately. You can use the APIs and extensions after you authenticate through the Identity API:

POST
/v2.0/tokens
Authenticate

Authenticates and generates a token.

 

The Identity API is a RESTful web service. It is the entry point to all service APIs. To access the Identity API, you must know its URL.

Each REST request against Identity requires the X-Auth-Token header. Clients obtain this token, along with the URL to other service APIs, by first authenticating against Identity with valid credentials.

To authenticate, you must provide either a user ID and password or a token.

If the authentication token has expired, this call returns the HTTP 401 status code.

If the token specified in the request has expired, this call returns the HTTP 404 status code.

The Identity API treats expired tokens as no longer valid tokens.

The deployment determines how long expired tokens are stored.

Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), userDisabled (403), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenantName (Optional) plain xsd:string

The tenant name. Both the tenantId and tenantName attributes are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.

tenantId (Optional) plain capi:UUID

The tenant ID. Both the tenantId and tenantName attributes are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.

passwordCredentials (Optional) plain xsd:string

A passwordCredentials object. To authenticate, you must provide either a user ID and password or a token.

username (Optional) plain xsd:string

The user name. Required if you include the passwordCredentials object. If you do not provide a password credentials, you must provide a token.

password (Optional) plain xsd:string

The password of the user. Required if you include the passwordCredentials object. If you do not provide a password credentials, you must provide a token.

token (Optional) plain xsd:string

A token object. Required if you do not provide password credentials.

id (Optional) plain xsd:string

The token ID. This is a required field in the token object.

Response parameters
Parameter Style Type Description
access plain xsd:string

An access object.

token plain xsd:string

A token object.

issued_at plain xsd:string

A timestamp that indicates when the token was issued.

expires plain xsd:string

A timestamp that indicates when the token expires.

id plain xsd:string

The authentication token. In the example, the token is my_id.

tenant plain xsd:string

A tenant object.

description plain xsd:string

The description of the tenant. If not set, this value is null.

enabled plain xsd:boolean

Indicates whether the tenant is enabled or disabled.

id plain xsd:string

The tenant ID.

name plain xsd:string

The tenant name.

serviceCatalog plain xsd:string

A serviceCatalog object.

endpoints plain xsd:string

One or more endpoints objects. Each object shows the adminURL, region, internalURL, id, and publicURL for the endpoint.

endpoints_links plain xsd:string

Links for the endpoint.

type plain xsd:string

Endpoint type.

name plain xsd:string

Endpoint name.

user plain xsd:string

A user object, which shows the username, roles_links, id, roles, and name.

metadata plain xsd:string

A metadata object. 

{
    "auth": {
        "tenantName": "demo",
        "passwordCredentials": {
            "username": "demo",
            "password": "secretsecret"
        }
    }
}

{
    "auth": {
        "tenantName": "demo",
        "token": {
            "id": "cbc36478b0bd8e67e89469c7749d4127"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<auth xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://docs.openstack.org/identity/api/v2.0"
  tenantName="demo">
  <passwordCredentials username="demo" password="secretsecret"/>
</auth>

{
    "access": {
        "token": {
            "issued_at": "2014-01-30T15:30:58.819584",
            "expires": "2014-01-31T15:30:58Z",
            "id": "aaaaa-bbbbb-ccccc-dddd",
            "tenant": {
                "description": null,
                "enabled": true,
                "id": "fc394f2ab2df4114bde39905f800dc57",
                "name": "demo"
            }
        },
        "serviceCatalog": [
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57",
                        "id": "2dad48f09e2a447a9bf852bcd93548ef",
                        "publicURL": "http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "compute",
                "name": "nova"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:9696/",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:9696/",
                        "id": "97c526db8d7a4c88bbb8d68db1bdcdb8",
                        "publicURL": "http://23.253.72.207:9696/"
                    }
                ],
                "endpoints_links": [],
                "type": "network",
                "name": "neutron"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57",
                        "id": "93f86dfcbba143a39a33d0c2cd424870",
                        "publicURL": "http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "volumev2",
                "name": "cinder"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8774/v3",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8774/v3",
                        "id": "3eb274b12b1d47b2abc536038d87339e",
                        "publicURL": "http://23.253.72.207:8774/v3"
                    }
                ],
                "endpoints_links": [],
                "type": "computev3",
                "name": "nova"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:3333",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:3333",
                        "id": "957f1e54afc64d33a62099faa5e980a2",
                        "publicURL": "http://23.253.72.207:3333"
                    }
                ],
                "endpoints_links": [],
                "type": "s3",
                "name": "s3"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:9292",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:9292",
                        "id": "27d5749f36864c7d96bebf84a5ec9767",
                        "publicURL": "http://23.253.72.207:9292"
                    }
                ],
                "endpoints_links": [],
                "type": "image",
                "name": "glance"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57",
                        "id": "37c83a2157f944f1972e74658aa0b139",
                        "publicURL": "http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "volume",
                "name": "cinder"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8773/services/Admin",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8773/services/Cloud",
                        "id": "289b59289d6048e2912b327e5d3240ca",
                        "publicURL": "http://23.253.72.207:8773/services/Cloud"
                    }
                ],
                "endpoints_links": [],
                "type": "ec2",
                "name": "ec2"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8080",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8080/v1/AUTH_fc394f2ab2df4114bde39905f800dc57",
                        "id": "16b76b5e5b7d48039a6e4cc3129545f3",
                        "publicURL": "http://23.253.72.207:8080/v1/AUTH_fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "object-store",
                "name": "swift"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:35357/v2.0",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:5000/v2.0",
                        "id": "26af053673df4ef3a2340c4239e21ea2",
                        "publicURL": "http://23.253.72.207:5000/v2.0"
                    }
                ],
                "endpoints_links": [],
                "type": "identity",
                "name": "keystone"
            }
        ],
        "user": {
            "username": "demo",
            "roles_links": [],
            "id": "9a6590b2ab024747bc2167c4e064d00d",
            "roles": [
                {
                    "name": "Member"
                },
                {
                    "name": "anotherrole"
                }
            ],
            "name": "demo"
        },
        "metadata": {
            "is_admin": 0,
            "roles": [
                "7598ac3c634d4c3da4b9126a5f67ca2b",
                "f95c0ab82d6045d9805033ee1fbc80d4"
            ]
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<access xmlns="http://docs.openstack.org/identity/api/v2.0">
        <token issued_at="2014-01-30T15:49:11.054709"
                expires="2014-01-31T15:49:11Z"
                id="aaaaa-bbbbb-ccccc-dddd">
                <tenant enabled="true" name="demo"
                        id="fc394f2ab2df4114bde39905f800dc57"/>
        </token>
        <serviceCatalog>
                <service type="compute" name="nova">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57"
                                internalURL="http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57"
                                id="2dad48f09e2a447a9bf852bcd93548ef"
                        />
                </service>
                <service type="network" name="neutron">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:9696/"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:9696/"
                                internalURL="http://23.253.72.207:9696/"
                                id="97c526db8d7a4c88bbb8d68db1bdcdb8"
                        />
                </service>
                <service type="volumev2" name="cinder">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57"
                                internalURL="http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57"
                                id="93f86dfcbba143a39a33d0c2cd424870"
                        />
                </service>
                <service type="computev3" name="nova">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:8774/v3"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:8774/v3"
                                internalURL="http://23.253.72.207:8774/v3"
                                id="3eb274b12b1d47b2abc536038d87339e"
                        />
                </service>
                <service type="s3" name="s3">
                        <endpoints_links/>
                        <endpoint adminURL="http://23.253.72.207:3333"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:3333"
                                internalURL="http://23.253.72.207:3333"
                                id="957f1e54afc64d33a62099faa5e980a2"
                        />
                </service>
                <service type="image" name="glance">
                        <endpoints_links/>
                        <endpoint adminURL="http://23.253.72.207:9292"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:9292"
                                internalURL="http://23.253.72.207:9292"
                                id="27d5749f36864c7d96bebf84a5ec9767"
                        />
                </service>
                <service type="volume" name="cinder">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57"
                                internalURL="http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57"
                                id="37c83a2157f944f1972e74658aa0b139"
                        />
                </service>
                <service type="ec2" name="ec2">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:8773/services/Admin"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:8773/services/Cloud"
                                internalURL="http://23.253.72.207:8773/services/Cloud"
                                id="289b59289d6048e2912b327e5d3240ca"
                        />
                </service>
                <service type="object-store" name="swift">
                        <endpoints_links/>
                        <endpoint adminURL="http://23.253.72.207:8080"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:8080/v1/AUTH_fc394f2ab2df4114bde39905f800dc57"
                                internalURL="http://23.253.72.207:8080/v1/AUTH_fc394f2ab2df4114bde39905f800dc57"
                                id="16b76b5e5b7d48039a6e4cc3129545f3"
                        />
                </service>
                <service type="identity" name="keystone">
                        <endpoints_links/>
                        <endpoint
                                adminURL="http://23.253.72.207:35357/v2.0"
                                region="RegionOne"
                                publicURL="http://23.253.72.207:5000/v2.0"
                                internalURL="http://23.253.72.207:5000/v2.0"
                                id="26af053673df4ef3a2340c4239e21ea2"
                        />
                </service>
        </serviceCatalog>
        <user username="demo" id="9a6590b2ab024747bc2167c4e064d00d"
                name="demo">
                <roles_links/>
                <role name="Member"/>
                <role name="anotherrole"/>
        </user>
        <metadata is_admin="0">
                <roles>
                        <role>7598ac3c634d4c3da4b9126a5f67ca2b</role>
                        <role>f95c0ab82d6045d9805033ee1fbc80d4</role>
                </roles>
        </metadata>
</access>

To get started with the APIs, see the OpenStack API Quick Start.