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. In exchange for a set of authentication credentials, the Identity service generates tokens. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project or domain.

The body of an authentication request must include a payload that specifies the authentication method, which is password or token, the credentials, and, optionally, the authorization scope. You can scope a token to a project or domain, or the token can be unscoped. You cannot scope a token to both a project and domain.

POST
/v3/auth/tokens
Password authentication with unscoped authorization

Authenticates an identity and generates a token. Uses the password authentication method. Authorization is unscoped.

 

The request body must include a payload that specifies the authentication method, which is password, and the user, by ID or name, and password credentials.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), conflict (409), Request Entity Too Large (413), Unsupported Media Type (415), Service Unavailable (503)
Request parameters
Parameter Style Type Description
nocatalog (Optional) query xsd:string

(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

auth plain xsd:dict

An auth object.

identity plain xsd:dict

An identity object.

methods plain xsd:list

The authentication method. For password authentication, specify password.

password plain xsd:dict

A password object. The password authentication method is used.

user plain xsd:dict

A user object.

id (Optional) plain csapi:UUID

The ID of the user.

Required if you do not specify the user name.

name (Optional) plain xsd:string

The user name.

Required if you do not specify the ID of the user.

If you specify the user name, you must also specify the domain, by ID or name.

domain (Optional) plain xsd:dict

A domain object. Required if you specify a user name.

id (Optional) plain csapi:UUID

The ID of the domain.

If you specify a user name, you must specify either a domain ID or domain name.

name (Optional) plain xsd:string

The name of the domain.

If you specify a user name, you must specify either a domain ID or domain name.

password plain xsd:string

The password for the user.

Response parameters
Parameter Style Type Description
X-Subject-Token header xsd:string

The authentication token.

An authentication response returns the token ID in this header rather than in the response body.

token plain xsd:dict

A token object.

methods plain xsd:list

The authentication method, which is password, token, or both methods.

Indicates the accumulated set of authentication methods that were used to obtain the token. For example, if the token was obtained by password authentication, it contains password. Later, if the token is exchanged by using the token authentication method one or more times, the subsequently created tokens contain both password and token in their methods attribute.

Unlike multi-factor authentication, the methods attribute merely indicates the methods that were used to authenticate the user in exchange for a token. The client is responsible for determining the total number of authentication factors.

expires_at plain xsd:dateTime

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

extras plain xsd:dict

A set of metadata key and value pairs, if any.

user plain xsd:dict

A user object.

domain plain xsd:dict

A domain object.

id plain csapi:UUID

The ID of the domain.

name plain xsd:string

The name of the domain.

id plain csapi:UUID

The ID of the user.

name plain xsd:string

The user name.

audit_ids plain xsd:list

A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token.

The first audit ID is the current audit ID for the token.

The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re-scoped token is one that was exchanged for another token of the same or different scope.

You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.

issued_at plain xsd:dateTime

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "423f19a4ac1e4f48bbb4180756e6eb6c",
                    "password": "devstacker"
                }
            }
        }
    }
}
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "name": "admin",
                    "domain": {
                        "id": "default"
                    },
                    "password": "devstacker"
                }
            }
        }
    }
}
{
    "token": {
        "methods": [
            "password"
        ],
        "expires_at": "2015-11-06T15:32:17.893769Z",
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "423f19a4ac1e4f48bbb4180756e6eb6c",
            "name": "admin"
        },
        "audit_ids": [
            "ZzZwkUflQfygX7pdYDBCQQ"
        ],
        "issued_at": "2015-11-06T14:32:17.893797Z"
    }
}
POST
/v3/auth/tokens
Password authentication with scoped authorization

Authenticates an identity and generates a token. Uses the password authentication method and scopes authorization to a project or domain.

 

The request body must include a payload that specifies the password authentication method, the credentials, and the project or domain authorization scope.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), conflict (409), Request Entity Too Large (413), Unsupported Media Type (415), Service Unavailable (503)
Request parameters
Parameter Style Type Description
nocatalog (Optional) query xsd:string

(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

auth plain xsd:dict

An auth object.

identity plain xsd:dict

An identity object.

methods plain xsd:list

The authentication method. For password authentication, specify password.

password plain xsd:dict

A password object. The password authentication method is used.

scope (Optional) plain xsd:dict

The authorization scope.

  • Specify project to scope to a project, by ID or name. If you specify the project by name, you must also specify the project domain to uniquely identify the project. Because a project can have the same name as its owning domain, the scope is determined, as follows:

    • If the project name is truly unique, the token is scoped to the project.

    • If a name clash exists between a project acting as a domain and a regular project within that domain, the token is scoped to the regular project.

    • In a name-clash situation, if the user wants the token scoped to the project acting as the domain, you must either specify use the project ID to specify the scope or rename either the project acting as a domain or the regular project.

    Alternatively, you can use a domain name to uniquely identify the project.

  • Specify domain to scope to a domain, by ID or name with equivalent results to project scoping. The catalog returned from a domain-scoped request contains all endpoints of a project-scoped catalog, excluding ones that require a project ID as part of their URL.

You cannot simultaneously scope a token to a project and domain.

user plain xsd:dict

A user object.

id (Optional) plain csapi:UUID

The ID of the user.

Required if you do not specify the user name.

name (Optional) plain xsd:string

The user name.

Required if you do not specify the ID of the user.

If you specify the user name, you must also specify the domain, by ID or name.

password plain xsd:string

The user password.

Response parameters
Parameter Style Type Description
X-Subject-Token header xsd:string

The authentication token.

An authentication response returns the token ID in this header rather than in the response body.

token plain xsd:dict

A token object.

methods plain xsd:list

The authentication method, which is password, token, or both methods.

Indicates the accumulated set of authentication methods that were used to obtain the token. For example, if the token was obtained by password authentication, it contains password. Later, if the token is exchanged by using the token authentication method one or more times, the subsequently created tokens contain both password and token in their methods attribute.

Unlike multi-factor authentication, the methods attribute merely indicates the methods that were used to authenticate the user in exchange for a token. The client is responsible for determining the total number of authentication factors.

roles plain xsd:list

A roles object.

id plain csapi:UUID

The ID for the role.

name plain xsd:string

The role name.

project plain xsd:dict

A project object.

domain plain xsd:dict

A domain object.

id plain csapi:UUID

The domain ID.

name plain xsd:string

The domain name.

id plain csapi:UUID

The ID for the project.

name plain xsd:string

The project name. The project can have the same name as its domain.

catalog plain xsd:list

A catalog object.

endpoints plain xsd:list

An endpoints object.

region_id plain csapi:UUID

(Since v3.2) The ID of the region that contains the service endpoint.

url plain xsd:string

The endpoint URL.

region plain xsd:string

(Deprecated in v3.2) The geographic location of the service endpoint.

interface plain xsd:string

The interface type, which describes the visibility of the endpoint.

Value is:

  • public. Visible by end users on a publicly available network interface.

  • internal. Visible by end users on an unmetered internal network interface.

  • admin. Visible by administrative users on a secure network interface.

id plain csapi:UUID

The ID for the region.

type plain xsd:string

The endpoint type.

id plain csapi:UUID

The endpoint UUID.

name plain xsd:string

The endpoint name.

expires_at plain xsd:dateTime

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

extras plain xsd:dict

A set of metadata key and value pairs, if any.

user plain xsd:dict

A user object.

domain plain xsd:dict

A domain object.

id plain csapi:UUID

The ID of the domain.

name plain xsd:string

The name of the domain.

id plain csapi:UUID

The ID of the user.

name plain xsd:string

The user name.

audit_ids plain xsd:list

A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token.

The first audit ID is the current audit ID for the token.

The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re-scoped token is one that was exchanged for another token of the same or different scope.

You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.

issued_at plain xsd:dateTime

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "project": {
                "id": "a6944d763bf64ee6a275f1263fae0352"
            }
        }
    }
}
{
    "token": {
        "methods": [
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "a6944d763bf64ee6a275f1263fae0352",
            "name": "admin"
        },
        "catalog": [
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:5000/v2.0",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "068d1b359ee84b438266cb736d81de97"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:35357/v2.0",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "8bfc846841ab441ca38471be6d164ced"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:5000/v2.0",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "beb6d358c3654b4bada04d4663b640b9"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "ae36c0dbb0634e1dbf711f9fc2359975"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "d286b51530144d90a4de52d214d3ad1e"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "d6e681dd4aab4ae5a0937ed60bb4ae33"
                    }
                ],
                "type": "compute_legacy",
                "id": "1c4bfbabe3b346b1bbe27a4b3258964f",
                "name": "nova_legacy"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v2/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "2dce7429526e44808235fe918063a914"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v2/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "a9a9929e6dc645c882ac1abd8bf73d38"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v2/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "c7d5f958df7f4c8da84db91094bdc198"
                    }
                ],
                "type": "volumev2",
                "id": "202382a1b8a94210bb3120af958092c4",
                "name": "cinderv2"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8080",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "29b58f1406804c8180ccc01793ff8038"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8080/v1/AUTH_a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "4c2c2968008c4e77973a5922e192d982"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8080/v1/AUTH_a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "f6e7b28008bf41eaa114176a15ac1410"
                    }
                ],
                "type": "object-store",
                "id": "52fecdef9ad543779c1312392cc2b115",
                "name": "swift"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9696/",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "6a2840dc63bf433592cd8bca2183eb3c"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9696/",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "7967cf45f8ab439a80cf24420e5ffd0e"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9696/",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "84943ce595264303bd44e5d6d79bea7b"
                    }
                ],
                "type": "network",
                "id": "67b993549db94296a853d635b48db3c9",
                "name": "neutron"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8888",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "2896609ef89741148bbd8c93babf5a12"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8888",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "30de385478fe4325849f98d1e45bc5e6"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8888",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "41256dc4b3c942daa383f940a9a56536"
                    }
                ],
                "type": "messaging",
                "id": "6fc9cc3e6b3843b899478554f9e297d3",
                "name": "zaqar"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9000",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "07ea5fe3ae784001a73f131fb1764bf4"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9000",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "31e709ecb15d4881806dbced4eb3e60e"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9000",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "a0c2a150a6ae4bbc85f1d428b9d78a1b"
                    }
                ],
                "type": "messaging-websocket",
                "id": "816031f798cc4ac7879eda0cf9cf033a",
                "name": "zaqar-websocket"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8773/",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "24df0277c2b6499ea6051bea8c59ff74"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8773/",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "438f4b3f3c314bbf988f1442cc3ddfa5"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8773/",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "90a1c9fab54c452fa02a59ff87165029"
                    }
                ],
                "type": "ec2",
                "id": "915e2a8b1f314d55bba28432c9d5c1de",
                "name": "ec2"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2.1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "2511589f262a407bb0071a814a480af4"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2.1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "9cf9209ae4fc4673a7295611001cf0ae"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2.1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "d200b2509e1343e3887dcc465b4fa534"
                    }
                ],
                "type": "compute",
                "id": "a226b3eeb5594f50bf8b6df94636ed28",
                "name": "nova"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8004/v1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "bf2fe80c2a614e438d3e55b00e85b9ff"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8004/v1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "bfc9615fc24e4045aaf719f060984bf1"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8004/v1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "c76cf9930b0f4ccea6b1157f80119cfc"
                    }
                ],
                "type": "orchestration",
                "id": "a5f7070bda40443fa3819fbdf1689af1",
                "name": "heat"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "3e321c2c6fa04152b3e86c18b91b93ae"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "55aef0f2557449d4946dc9461b73a63b"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v1/a6944d763bf64ee6a275f1263fae0352",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "7c91a66a200e458ca6e4e00fddf4d98b"
                    }
                ],
                "type": "volume",
                "id": "b6b5edc3fc384b6787149e91b3b31988",
                "name": "cinder"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9292",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "512c10d230874ad295662157eeab0135"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9292",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "614b1ab241da47a8b3a4e8f67b771446"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9292",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "9cef78a4286c42f3b977fbe4d5f927a6"
                    }
                ],
                "type": "image",
                "id": "d512f8860c0f45cf99b1c3cef86cfd97",
                "name": "glance"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8000/v1",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "7f776d5a83d346b48e519555362b1da6"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8000/v1",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "8303a7225a2d439fa39905c6a20202c3"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8000/v1",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "942fa998d1c644e0b0c085d5a0995a13"
                    }
                ],
                "type": "cloudformation",
                "id": "ed0805af6ee54a19ad7e5add8465ac41",
                "name": "heat-cfn"
            }
        ],
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin"
        },
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "issued_at": "2015-11-07T01:58:43.578929Z"
    }
}
POST
/v3/auth/tokens
Password authentication with explicit unscoped authorization

Authenticates an identity and generates a token. Uses the password authentication method with explicit unscoped authorization.

 

The request body must include a payload that specifies the password authentication method, the credentials, and the unscoped authorization scope.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), conflict (409), Request Entity Too Large (413), Unsupported Media Type (415), Service Unavailable (503)
Request parameters
Parameter Style Type Description
nocatalog (Optional) query xsd:string

(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

auth plain xsd:dict

An auth object.

identity plain xsd:dict

An identity object.

methods plain xsd:list

The authentication method. For password authentication, specify password.

password plain xsd:dict

A password object. The password authentication method is used.

scope (Optional) plain xsd:string

The authorization scope.

(Since v3.4) Specify unscoped to make an explicit unscoped token request, which returns an unscoped response without any authorization. This request behaves the same as a token request with no scope where the user has no default project defined.

If you do not make an explicit unscoped token request and your role has a default project, the response might return a project-scoped token. If a default project is not defined, a token is issued without an explicit scope of authorization, which is the same as asking for an explicit unscoped token.

user plain xsd:dict

A user object.

id (Optional) plain csapi:UUID

The ID of the user.

Required if you do not specify the user name.

name (Optional) plain xsd:string

The user name.

Required if you do not specify the ID of the user.

If you specify the user name, you must also specify the domain, by ID or name.

password plain xsd:string

The user password.

Response parameters
Parameter Style Type Description
X-Subject-Token header xsd:string

The authentication token.

An authentication response returns the token ID in this header rather than in the response body.

token plain xsd:dict

A token object.

methods plain xsd:list

The authentication method, which is password, token, or both methods.

Indicates the accumulated set of authentication methods that were used to obtain the token. For example, if the token was obtained by password authentication, it contains password. Later, if the token is exchanged by using the token authentication method one or more times, the subsequently created tokens contain both password and token in their methods attribute.

Unlike multi-factor authentication, the methods attribute merely indicates the methods that were used to authenticate the user in exchange for a token. The client is responsible for determining the total number of authentication factors.

roles plain xsd:list

A roles object.

id plain csapi:UUID

The ID for the role.

name plain xsd:string

The role name.

expires_at plain xsd:dateTime

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

extras plain xsd:dict

A set of metadata key and value pairs, if any.

user plain xsd:dict

A user object.

domain plain xsd:dict

A domain object.

id plain csapi:UUID

The ID of the domain.

name plain xsd:string

The name of the domain.

id plain csapi:UUID

The ID of the user.

name plain xsd:string

The user name.

audit_ids plain xsd:list

A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token.

The first audit ID is the current audit ID for the token.

The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re-scoped token is one that was exchanged for another token of the same or different scope.

You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.

issued_at plain xsd:dateTime

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": "unscoped"
    }
}
{
    "token": {
        "methods": [
            "password"
        ],
        "expires_at": "2015-11-09T01:42:57.527363Z",
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin"
        },
        "audit_ids": [
            "lC2Wj1jbQe-dLjLyOx4qPQ"
        ],
        "issued_at": "2015-11-09T00:42:57.527404Z"
    }
}
POST
/v3/auth/tokens
Token authentication with unscoped authorization

Authenticates an identity and generates a token. Uses the token authentication method. Authorization is unscoped.

 

In the request body, provide the token ID.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), conflict (409), Request Entity Too Large (413), Unsupported Media Type (415), Service Unavailable (503)
Request parameters
Parameter Style Type Description
nocatalog (Optional) query xsd:string

(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

auth plain xsd:dict

An auth object.

identity plain xsd:dict

An identity object.

methods plain xsd:list

The authentication method. For token authentication, specify token.

token plain xsd:dict

A token object. The token authentication method is used. This method is typically used in combination with a request to change authorization scope.

id (Optional) plain csapi:UUID

A token ID.

Response parameters
Parameter Style Type Description
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

X-Subject-Token header xsd:string

The authentication token.

An authentication response returns the token ID in this header rather than in the response body.

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        }
    }
}
{
    "token": {
        "methods": [
            "token"
        ],
        "expires_at": "2015-11-05T22:00:11.000000Z",
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "10a2e6e717a245d9acad3e5f97aeca3d",
            "name": "admin"
        },
        "audit_ids": [
            "mAjXQhiYRyKwkB4qygdLVg"
        ],
        "issued_at": "2015-11-05T21:00:33.819948Z"
    }
}
POST
/v3/auth/tokens
Token authentication with scoped authorization

Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project or domain.

 

In the request body, provide the token ID and the project or domain authorization scope.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), conflict (409), Request Entity Too Large (413), Unsupported Media Type (415), Service Unavailable (503)
Request parameters
Parameter Style Type Description
nocatalog (Optional) query xsd:string

(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

auth plain xsd:dict

An auth object.

identity plain xsd:dict

An identity object.

methods plain xsd:list

The authentication method. For token authentication, specify token.

token plain xsd:dict

A token object. The token authentication method is used. This method is typically used in combination with a request to change authorization scope.

id (Optional) plain csapi:UUID

A token ID.

scope (Optional) plain xsd:dict

The authorization scope.

  • Specify project to scope to a project, by ID or name. If you specify the project by name, you must also specify the project domain to uniquely identify the project. Because a project can have the same name as its owning domain, the scope is determined, as follows:

    • If the project name is truly unique, the token is scoped to the project.

    • If a name clash exists between a project acting as a domain and a regular project within that domain, the token is scoped to the regular project.

    • In a name-clash situation, if the user wants the token scoped to the project acting as the domain, you must either specify use the project ID to specify the scope or rename either the project acting as a domain or the regular project.

    Alternatively, you can use a domain name to uniquely identify the project.

  • Specify domain to scope to a domain, by ID or name with equivalent results to project scoping. The catalog returned from a domain-scoped request contains all endpoints of a project-scoped catalog, excluding ones that require a project ID as part of their URL.

You cannot simultaneously scope a token to a project and domain.

audit_ids plain xsd:list

A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token.

The first audit ID is the current audit ID for the token.

The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re-scoped token is one that was exchanged for another token of the same or different scope.

You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.

Response parameters
Parameter Style Type Description
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

X-Subject-Token header xsd:string

The authentication token.

An authentication response returns the token ID in this header rather than in the response body.

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "project": {
                "id": "5b50efd009b540559104ee3c03bbb2b7"
            }
        }
    }
}
{
    "token": {
        "methods": [
            "token"
        ],
        "roles": [
            {
                "id": "5090055d6bd547dc83e0e8f070803708",
                "name": "admin"
            }
        ],
        "expires_at": "2015-11-05T22:00:11.000000Z",
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "5b50efd009b540559104ee3c03bbb2b7",
            "name": "admin"
        },
        "catalog": [
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9292",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "b2605da9b25943beb49b2bd86aca2202"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9292",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "c4d1184caf8c4351bff4bf502a09684e"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9292",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "cd73bda89e3948738c2721a8c3acac54"
                    }
                ],
                "type": "image",
                "id": "495df2483dc145dbb6b34bfbdd787aae",
                "name": "glance"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8773/",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "7d03218a7f4246e8b9e3992318bf5397"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8773/",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "9ad7f8ce438c4212b8aac930bca04c86"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8773/",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "d84aad1a45c44e4da09b719167383049"
                    }
                ],
                "type": "ec2",
                "id": "54204024bb7d4665a8efc34fc758f1f7",
                "name": "ec2"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9000",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "1077687c18514490a3ec980eadd1bd13"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9000",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "1e86d8bef1514c3fba8d157a22ccce88"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9000",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "f6a6b7bbba66443ead3a0e31a008c271"
                    }
                ],
                "type": "messaging-websocket",
                "id": "6b8655af7d044a15bec3cdca4f2919f8",
                "name": "zaqar-websocket"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8004/v1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "083663fd231e40ad97384ad3efb9f1b7"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8004/v1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "0f4b7054ea27450eac43f685a4fc1d2c"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8004/v1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "5f3ea39df2e44378b1802a1a87ef9ac4"
                    }
                ],
                "type": "orchestration",
                "id": "6d6346ff2ca842e5968373fbb93e231f",
                "name": "heat"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2.1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "bc2230a70d6a444e9fba75b85fbda41b"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2.1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "d8102dc2b9984d04b30b91b0a6037470"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2.1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "f8253a53edd749bf8b107a53a5d47a82"
                    }
                ],
                "type": "compute",
                "id": "75df965385cc4120a17110c1fde00182",
                "name": "nova"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:35357/v2.0",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "0ceeb58592274caea5bc942a07d5473f"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:5000/v2.0",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "8126f2c7021d413e9c98ec3a0ba0fd58"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:5000/v2.0",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "c693879254544e3fb502e795a3f6acc8"
                    }
                ],
                "type": "identity",
                "id": "78aad571d38049e69c866c2abac76af6",
                "name": "keystone"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "3654138dc64a45aeb5a8153f2a089c74"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "7a0d12d0b7314afd9b53d1618ab546ea"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v1/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "82b68ff3aedb43e2acc8307234d3fd0b"
                    }
                ],
                "type": "volume",
                "id": "80491007c0ab462daaa9087250325f59",
                "name": "cinder"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8000/v1",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "24dfa252fba64469b8b1a832f04bded9"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8000/v1",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "e0a01d6cd3be4f6abcc72367b2d87993"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8000/v1",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "f33f79d42df247e1bf6daf43a548b014"
                    }
                ],
                "type": "cloudformation",
                "id": "ac5cc6e3c62840818ab338c981d5603f",
                "name": "heat-cfn"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9696/",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "3e78c357b3c8469fbea12eb681f88a0c"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9696/",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "89d2aad3dc8e478fbabb21dd7db0962a"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:9696/",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "b6d4a8cf5e4042848a749a3116497e55"
                    }
                ],
                "type": "network",
                "id": "b33660edd1eb45e485f7e5f14401a739",
                "name": "neutron"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8888",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "1f8287cf963948778ab0eb109d9f857d"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8888",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "3adf5f9cc5184d92af5ff0fdef043e4a"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8888",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "f747223060b3414f947fdcdca2ce8714"
                    }
                ],
                "type": "messaging",
                "id": "cf3e38e9aed54e2d84ea64485317d7a0",
                "name": "zaqar"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "08f507ccb552476b98f3af7718f25557"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "d20091ba591347b2b419e5fbde9b7976"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8774/v2/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "e6b667776e7245dea6e39f2820e080b0"
                    }
                ],
                "type": "compute_legacy",
                "id": "d442e96b273a48018567aeec5800c3e0",
                "name": "nova_legacy"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v2/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "012c78a6694a494995c58d5955fb7822"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v2/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "802d5de210874f068ba31c7e27c29d70"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8776/v2/5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "b37ada66e02e44c9a9a7976d77365503"
                    }
                ],
                "type": "volumev2",
                "id": "d93e78c7967f49acbdd732b9dd97e0d0",
                "name": "cinderv2"
            },
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8080/v1/AUTH_5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "265ce88a0e1642fc90b2ec20ccb279ff"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8080",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "500b7f066d39492faff8a3f710fb5a2f"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://23.253.248.171:8080/v1/AUTH_5b50efd009b540559104ee3c03bbb2b7",
                        "region": "RegionOne",
                        "interface": "internal",
                        "id": "a33b0684f817405280df1f5600777a75"
                    }
                ],
                "type": "object-store",
                "id": "da1b1b5c529946fcb3ee3abdcf376fcb",
                "name": "swift"
            }
        ],
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "10a2e6e717a245d9acad3e5f97aeca3d",
            "name": "admin"
        },
        "audit_ids": [
            "wLc7nDMsQiKqf8VFU4ySpg"
        ],
        "issued_at": "2015-11-05T21:32:30.505384Z"
    }
}

To get started with the APIs, see the OpenStack API Guide.