Identity API v3 (CURRENT)

The Identity service generates authentication tokens that permit access to the OpenStack services REST APIs. Clients obtain this token and the URL endpoints for other service APIs by supplying their valid credentials to the authentication service.

Each time you make a REST API request to an OpenStack service, you supply your authentication token in the X-Auth-Token request header.

Like most OpenStack projects, OpenStack Identity protects its APIs by defining policy rules based on a role-based access control (RBAC) approach.

The Identity service keystone.conf configuration file sets the name and location of a JSON policy file that stores these rules.

For information about Identity API protection, see Identity API protection with role-based access control (RBAC) in the OpenStack Cloud Administrator Guide.

This page lists the Identity API operations in the following order:

Authentication and token management (auth, tokens)

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.

Tokens have IDs, which the Identity API returns in the X-Subject-Token response header.

Also, validates an authentication token and lists the domains, projects, roles, and endpoints to which the token gives access. Forces the immediate revocation of a token.

After you obtain an authentication token, you can:

  • Make REST API requests to other OpenStack services. You supply the ID of your authentication token in the X-Auth-Token request header.

  • Validate your authentication token and list the domains, projects, roles, and endpoints that your token gives you access to.

  • Use your token to request another token scoped for a different domain and project.

  • Force the immediate revocation of a token.

  • List revoked public key infrastructure (PKI) tokens.

The Identity API treats expired tokens as no longer valid tokens. The deployment determines how long expired tokens are stored.

These authentication errors can occur:

Authentication errors
Response code Description

Bad Request (400)

The Identity service failed to parse the request as expected. One of the following errors occurred:

  • A required attribute was missing.

  • An attribute that is not allowed was specified, such as an ID on a POST request in a basic CRUD operation.

  • An attribute of an unexpected data type was specified.

Unauthorized (401)

One of the following errors occurred:

  • Authentication was not performed.

  • The specified X-Auth-Token header is not valid.

  • The authentication credentials are not valid.

Forbidden (403)

The identity was successfully authenticated but it is not authorized to perform the requested action.

Not Found (404)

An operation failed because a referenced entity cannot be found by ID. For a POST request, the referenced entity might be specified in the request body rather than in the resource path.

Conflict (409)

A POST or PATCH operation failed. For example, a client tried to update a unique attribute for an entity, which conflicts with that of another entity in the same collection.

Or, a client issued a create operation twice on a collection with a user-defined, unique attribute. For example, a client made a POST /users request two times for the unique, user-defined name attribute for a user entity.

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 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
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
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"
    }
}
GET
/v3/auth/tokens
Validate and show information for token

Validates and shows information for a token, including its expiration date and authorization scope.

 

Pass your own token in the X-Auth-Token request header.

Pass the token that you want to validate in the X-Subject-Token request header.

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request 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 for which you want to perform the operation.

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.

token plain xsd:dict

A token object.

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.

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.

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.

user plain xsd:dict

A user object.

domain (Optional) plain xsd:dict

Specify either id or name to uniquely identify the domain.

id plain csapi:UUID

The domain ID.

links plain xsd:string

The links for the domain resource.

name plain xsd:string

The domain name.

id plain csapi:UUID

The user ID.

links plain xsd:dict

The links for the user resource.

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.

extras plain xsd:dict

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

catalog plain xsd:list

A catalog object.

project plain xsd:dict

A project object.

roles plain xsd:list

A roles object.

Headers:
X-Auth-Token: 1dd7e3
X-Subject-Token: c67580
{
    "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"
    }
}
HEAD
/v3/auth/tokens
Check token

Validates a token.

 

This call is similar to GET /auth/tokens but no response body is provided even in the X-Subject-Token header.

The Identity API returns the same response as when the subject token was issued by POST /auth/tokens even if an error occurs because the token is not valid. An HTTP 204 response code indicates that the X-Subject-Token is valid.

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request 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 for which you want to perform the operation.

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.

Headers:
X-Auth-Token: 1dd7e3
X-Subject-Token: c67580

This operation does not return a response body.

DELETE
/v3/auth/tokens
Revoke token

Revokes a token.

 

This call is similar to the HEAD /auth/tokens call except that the X-Subject-Token token is immediately not valid, regardless of the expires_at attribute value. An additional X-Auth-Token is not required.

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
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

X-Subject-Token header xsd:string

The authentication token for which you want to perform the operation.

Headers:
X-Auth-Token: 1dd7e3
X-Subject-Token: c67580

This operation does not return a response body.

Credentials (credentials)

In exchange for a set of authentication credentials that the user submits, the Identity service generates and returns a token. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project or domain.

You can list all credentials, and create, show details for, update, and delete a credential.

POST
/v3/credentials
Create credential

Creates a credential.

 

The following example shows how to create an EC2-style credential. The credential blob is a string that contains a JSON-serialized dictionary with the access and secret keys. This format is required when you specify the ec2 type. To specify other credentials, such as access_key, change the type and contents of the data blob.

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
credential plain xsd:dict

A credential object.

blob plain xsd:string

The credential itself, as a serialized blob.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The credential type, such as ec2 or cert. The implementation determines the list of supported types.

user_id plain csapi:UUID

The ID of the user who owns the credential.

Response parameters
Parameter Style Type Description
credential plain xsd:dict

A credential object.

user_id plain csapi:UUID

The ID of the user who owns the credential.

links plain xsd:dict

The links for the credential resource.

blob plain xsd:string

The credential itself, as a serialized blob.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The credential type, such as ec2 or cert. The implementation determines the list of supported types.

id plain csapi:UUID

The UUID for the credential.

{
    "credential": {
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "user_id": "bb5476fd12884539b41d5a88f838d773"
    }
}
{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773",
        "links": {
            "self": "http://localhost:5000/v3/credentials/3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510"
        },
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "id": "3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510"
    }
}
GET
/v3/credentials
List credentials

Lists all credentials.

 

Optionally, you can include the user_id query parameter in the URI to filter the response by a user.

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
user_id (Optional) query csapi:UUID

Filters the response by a user ID.

Response parameters
Parameter Style Type Description
credentials plain xsd:list

A credentials object.

user_id plain csapi:UUID

The ID of the user who owns the credential.

links plain xsd:dict

The links for the credential resource.

blob plain xsd:string

The credential itself, as a serialized blob.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The credential type, such as ec2 or cert. The implementation determines the list of supported types.

id plain csapi:UUID

The UUID for the credential.

links plain xsd:dict

The links for the credentials resource.

{
    "credentials": [
        {
            "user_id": "bb5476fd12884539b41d5a88f838d773",
            "links": {
                "self": "http://localhost:5000/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
            },
            "blob": "{\"access\": \"a42a27755ce6442596b049bd7dd8a563\", \"secret\": \"71faf1d40bb24c82b479b1c6fbbd9f0c\", \"trust_id\": null}",
            "project_id": "6e01855f345f4c59812999b5e459137d",
            "type": "ec2",
            "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
        },
        {
            "user_id": "6f556708d04b4ea6bc72d7df2296b71a",
            "links": {
                "self": "http://localhost:5000/v3/credentials/2441494e52ab6d594a34d74586075cb299489bdd1e9389e3ab06467a4f460609"
            },
            "blob": "{\"access\": \"7da79ff0aa364e1396f067e352b9b79a\", \"secret\": \"7a18d68ba8834b799d396f3ff6f1e98c\", \"trust_id\": null}",
            "project_id": "1a1d14690f3c4ec5bf5f321c5fde3c16",
            "type": "ec2",
            "id": "2441494e52ab6d594a34d74586075cb299489bdd1e9389e3ab06467a4f460609"
        },
        {
            "user_id": "c14107e65d5c4a7f8894fc4b3fc209ff",
            "links": {
                "self": "http://localhost:5000/v3/credentials/3397b204b5f04c495bcdc8f34c8a39996f280f9172658241873e15f070ec79d7"
            },
            "blob": "{\"access\": \"db9c58a558534a10a070110de4f9f20c\", \"secret\": \"973e790b88db447ba6f93bca02bc745b\", \"trust_id\": null}",
            "project_id": "7396e43183db40dcbf40dd727637b548",
            "type": "ec2",
            "id": "3397b204b5f04c495bcdc8f34c8a39996f280f9172658241873e15f070ec79d7"
        },
        {
            "user_id": "915cc5f8cca6466aba6c6be06cbabfdf",
            "links": {
                "self": "http://localhost:5000/v3/credentials/352d5dd7a4aa19c4f2f23ee288bf65dc23a0bc293f40ffd2128ffe6a8cf3e871"
            },
            "blob": "{\"access\": \"817c6c3487a440c1a0b1d3f92b30ca37\", \"secret\": \"47d681117d1c46e69a0c9ec811dae2e9\", \"trust_id\": null}",
            "project_id": "2bf9767f9db949ee8364262a28a23062",
            "type": "ec2",
            "id": "352d5dd7a4aa19c4f2f23ee288bf65dc23a0bc293f40ffd2128ffe6a8cf3e871"
        },
        {
            "user_id": "bb5476fd12884539b41d5a88f838d773",
            "links": {
                "self": "http://localhost:5000/v3/credentials/3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510"
            },
            "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
            "project_id": "731fc6f265cd486d900f16e84c5cb594",
            "type": "ec2",
            "id": "3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510"
        },
        {
            "user_id": "bb5476fd12884539b41d5a88f838d773",
            "links": {
                "self": "http://localhost:5000/v3/credentials/6b7d803fc03b85866904b6b79e0a8fa1f4013b584163b4477eed96717eb402c0"
            },
            "blob": "{\"access\": \"f2ba45670b504a518b46e920d760fde2\", \"secret\": \"bf7fff2b3a844730b2db793411756e55\", \"trust_id\": null}",
            "project_id": "731fc6f265cd486d900f16e84c5cb594",
            "type": "ec2",
            "id": "6b7d803fc03b85866904b6b79e0a8fa1f4013b584163b4477eed96717eb402c0"
        },
        {
            "user_id": "2b657f6742ac416697e6821b3b2ee785",
            "links": {
                "self": "http://localhost:5000/v3/credentials/7d391b869631e5c4836708ea3bb3e0a5cbe0481201b5f0ddd5685ad3b3faa564"
            },
            "blob": "{\"access\": \"a1525da4e7c0438ebf3058372d637b59\", \"secret\": \"c9165d2542b141e8b2a1ff61a5f5487c\", \"trust_id\": null}",
            "project_id": "2bf9767f9db949ee8364262a28a23062",
            "type": "ec2",
            "id": "7d391b869631e5c4836708ea3bb3e0a5cbe0481201b5f0ddd5685ad3b3faa564"
        },
        {
            "user_id": "bb5476fd12884539b41d5a88f838d773",
            "links": {
                "self": "http://localhost:5000/v3/credentials/7ef4faa904ae7b8b4ddc7bad15b05ee359dad7d7a9b82861d4ad92fdbbb2eb4e"
            },
            "blob": "{\"access\": \"7d7559359b57419eb5f5f5dcd65ab57d\", \"secret\": \"570652bcf8c2483c86eb29e9734eed3c\", \"trust_id\": null}",
            "project_id": "731fc6f265cd486d900f16e84c5cb594",
            "type": "ec2",
            "id": "7ef4faa904ae7b8b4ddc7bad15b05ee359dad7d7a9b82861d4ad92fdbbb2eb4e"
        },
        {
            "user_id": "aedb193e9bb8400485f8d8426f7a031f",
            "links": {
                "self": "http://localhost:5000/v3/credentials/9c1c428d8e0e8338a5e16489ecfff9962f2b00f984ce4c7e9015e4003f478df8"
            },
            "blob": "{\"access\": \"b3a6e5f4427c47e9b202264d91a19e49\", \"secret\": \"d9eb470f503f4b46932de38db7a79402\", \"trust_id\": null}",
            "project_id": "a2672ecf9dd34c6980448b25a47e0947",
            "type": "ec2",
            "id": "9c1c428d8e0e8338a5e16489ecfff9962f2b00f984ce4c7e9015e4003f478df8"
        },
        {
            "user_id": "c14107e65d5c4a7f8894fc4b3fc209ff",
            "links": {
                "self": "http://localhost:5000/v3/credentials/e2c35ac2becb0fca3c3c2f035692a4f46a9cbf3b6e86c8a47f5aafe837d78a05"
            },
            "blob": "{\"access\": \"1ed843b1bd4a409f9562400085adbaa4\", \"secret\": \"236ab24db1f04ec995fcf618ed4fc0f5\", \"trust_id\": null}",
            "project_id": "6e01855f345f4c59812999b5e459137d",
            "type": "ec2",
            "id": "e2c35ac2becb0fca3c3c2f035692a4f46a9cbf3b6e86c8a47f5aafe837d78a05"
        }
    ],
    "links": {
        "self": "http://localhost:5000/v3/credentials",
        "previous": null,
        "next": null
    }
}
GET
/v3/credentials/​{credential_id}​
Show credential details

Shows details for a credential.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
credential_id URI csapi:UUID

The UUID for the credential.

Response parameters
Parameter Style Type Description
credential plain xsd:dict

A credential object.

user_id plain csapi:UUID

The ID of the user who owns the credential.

links plain xsd:dict

The links for the credential resource.

blob plain xsd:string

The credential itself, as a serialized blob.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The credential type, such as ec2 or cert. The implementation determines the list of supported types.

id plain csapi:UUID

The UUID for the credential.

{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773",
        "links": {
            "self": "http://localhost:5000/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
        },
        "blob": "{\"access\": \"a42a27755ce6442596b049bd7dd8a563\", \"secret\": \"71faf1d40bb24c82b479b1c6fbbd9f0c\", \"trust_id\": null}",
        "project_id": "6e01855f345f4c59812999b5e459137d",
        "type": "ec2",
        "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
    }
}

This operation does not accept a request body.

PATCH
/v3/credentials/​{credential_id}​
Update credential

Updates a credential.

 
Normal response codes
200
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
credential_id URI csapi:UUID

The UUID for the credential.

credential plain xsd:dict

A credential object.

blob (Optional) plain xsd:string

The credential itself, as a serialized blob.

project_id (Optional) plain csapi:UUID

The UUID for the associated project.

type (Optional) plain xsd:string

The credential type, such as ec2 or cert. The implementation determines the list of supported types.

user_id (Optional) plain csapi:UUID

The ID of the user who owns the credential.

Response parameters
Parameter Style Type Description
credential plain xsd:dict

A credential object.

user_id plain csapi:UUID

The ID of the user who owns the credential.

links plain xsd:dict

The links for the credential resource.

blob plain xsd:string

The credential itself, as a serialized blob.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The credential type, such as ec2 or cert. The implementation determines the list of supported types.

id plain csapi:UUID

The UUID for the credential.

{
    "credential": {
        "blob": "{\"access\":\"181920\",\"secrete\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "user_id": "bb5476fd12884539b41d5a88f838d773"
    }
}
{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773",
        "links": {
            "self": "http://localhost:5000/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
        },
        "blob": "{\"access\":\"181920\",\"secrete\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
    }
}
DELETE
/v3/credentials/​{credential_id}​
Delete credential

Deletes a credential.

 
Normal response codes
204
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
credential_id URI csapi:UUID

The UUID for the credential.

This operation does not accept a request body and does not return a response body.

Domains (domains, users, groups, roles)

A domain is a collection of users, groups, and projects. Each group and project is owned by exactly one domain.

Each domain defines a namespace where certain API-visible name attributes exist, which affects whether those names must be globally unique or unique within that domain. In the Identity API, the uniqueness of these attributes is as follows:

  • Domain name. Globally unique across all domains.

  • Role name. Globally unique across all domains.

  • User name. Unique within the owning domain.

  • Project name. Unique within the owning domain.

  • Group name. Unique within the owning domain.

GET
/v3/domains
List domains

Lists all domains.

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

Filters the response by a domain name.

enabled (Optional) query xsd:string

Filters the response by either enabled (true) or disabled (false) domains.

Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

Response parameters
Parameter Style Type Description
domains plain xsd:list

A domains object.

description plain xsd:string

The domain description.

enabled plain xsd:boolean

Indicates whether the domain is enabled or disabled.

If set to true, the domain is enabled. Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

If set to false, the domain is disabled. Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

id plain csapi:UUID

The domain ID.

links plain xsd:dict

The links for the domain resource.

name plain xsd:string

The domain name.

links plain xsd:dict

The links for the domains resource.

{
    "domains": [
        {
            "description": "Used for swift functional testing",
            "enabled": true,
            "id": "5a75994a383c449184053ff7270c4e91",
            "links": {
                "self": "http://localhost:5000/v3/domains/5a75994a383c449184053ff7270c4e91"
            },
            "name": "swift_test"
        },
        {
            "description": "Owns users and tenants (i.e. projects) available on Identity API v2.",
            "enabled": true,
            "id": "default",
            "links": {
                "self": "http://localhost:5000/v3/domains/default"
            },
            "name": "Default"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/domains"
    }
}
POST
/v3/domains
Create domain

Creates a domain.

 
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
domain plain xsd:dict

A domain object.

description (Optional) plain xsd:string

The domain description.

enabled (Optional) plain xsd:boolean

Enables or disables the domain.

Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

To enable the domain, set to true. To disable the domain, set to false. Default is true.

name plain xsd:string

The domain name.

Response parameters
Parameter Style Type Description
domain plain xsd:dict

A domain object.

description plain xsd:string

The domain description.

enabled plain xsd:boolean

Indicates whether the domain is enabled or disabled.

If set to true, the domain is enabled. Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

If set to false, the domain is disabled. Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

id plain csapi:UUID

The domain ID.

links plain xsd:dict

The links for the domain resource.

name plain xsd:string

The domain name.

{
    "domain": {
        "description": "Domain description",
        "enabled": true,
        "name": "myDomain"
    }
}
{
    "domain": {
        "description": "Domain description",
        "enabled": true,
        "id": "161718",
        "links": {
            "self": "http://identity:35357/v3/domains/161718"
        },
        "name": "myDomain"
    }
}
GET
/v3/domains/​{domain_id}​
Show domain details

Shows details for a domain.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

Response parameters
Parameter Style Type Description
domain plain xsd:dict

A domain object.

description plain xsd:string

The domain description.

enabled plain xsd:boolean

Indicates whether the domain is enabled or disabled.

If set to true, the domain is enabled. Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

If set to false, the domain is disabled. Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

id plain csapi:UUID

The domain ID.

links plain xsd:dict

The links for the domain resource.

name plain xsd:string

The domain name.

{
    "domain": {
        "description": "Owns users and tenants (i.e. projects) available on Identity API v2.",
        "enabled": true,
        "id": "default",
        "links": {
            "self": "http://localhost:5000/v3/domains/default"
        },
        "name": "Default"
    }
}

This operation does not accept a request body.

PATCH
/v3/domains/​{domain_id}​
Update domain

Updates a domain.

 
Normal response codes
200
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
domain_id URI csapi:UUID

The domain ID.

domain plain xsd:dict

A domain object.

enabled (Optional) plain xsd:boolean

Enables or disables the domain.

Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

To enable the domain, set to true. To disable the domain, set to false. Default is true.

description (Optional) plain xsd:string

The domain description.

name (Optional) plain xsd:string

The domain name.

Response parameters
Parameter Style Type Description
domain plain xsd:dict

A domain object.

links plain xsd:dict

The links for the domain resource.

enabled plain xsd:boolean

Indicates whether the domain is enabled or disabled.

If set to true, the domain is enabled. Users can authorize against an enabled domain and any of its projects. Users that are owned by an enabled domain can authenticate and receive additional authorization.

If set to false, the domain is disabled. Users cannot authorize against a disabled domain or any of its projects. Users that are owned by a disabled domain cannot authenticate or receive additional authorization. All tokens that are authorized for a disabled domain or its projects become no longer valid. If you reenable the domain, these tokens are not re-enabled.

description plain xsd:string

The domain description.

name plain xsd:string

The domain name.

id plain csapi:UUID

The domain ID.

{
    "domain": {
        "description": "Owns users and projects on Identity API v2."
    }
}
{
    "domain": {
        "links": {
            "self": "http://localhost:5000/v3/domains/default"
        },
        "enabled": true,
        "description": "Owns users and projects on Identity API v2.",
        "name": "Default",
        "id": "default"
    }
}
DELETE
/v3/domains/​{domain_id}​
Delete domain

Deletes a domain.

 

To minimize the risk of accidentally deleting a domain, you must first disable the domain by using the update domain method.

When you delete a domain, this call also deletes all entities owned by it, such as users, groups, and projects, and any credentials and granted roles that relate to those entities.

(Since v3.6) The deletion of a non-leaf domain in a domain hierarchy tree is not allowed and fails with a Bad Request (400) response code.

If you try to delete an enabled domain, this call returns the Forbidden (403) response code.

Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

This operation does not accept a request body and does not return a response body.

Domain configuration (domains, config) (since v3.4) (EXPERIMENTAL)

You can manage domain-specific configuration options.

Domain-specific configuration options are structured within their group objects. The API supports only the identity and ldap groups. These groups override the default configuration settings for the storage of users and groups by the Identity server.

You can create, update, and delete domain-specific configuration options by using the HTTP PUT, PATCH, and DELETE methods. When updating, it is only necessary to include those options that are being updated.

To create an option, use the PUT method. The Identity API does not return options that are considered sensitive, although you can create and update these options. The only option currently considered sensitive is the password option within the ldap group.

The API enables you to include sensitive options as part of non- sensitive options. For example, you can include the password as part of the url option.

If you try to create or update configuration options for groups other than the identity or ldap groups, the Forbidden (403) response code is returned.

For information about how to integrate the Identity service with LDAP, see Integrate Identity with LDAP.

GET
/v3/domains/​{domain_id}​/config
Show domain configuration

Shows details for a domain configuration.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

Response parameters
Parameter Style Type Description
config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

{
    "config": {
        "identity": {
            "driver": "keystone.identity.backends.ldap.Identity"
        },
        "ldap": {
            "url": "http://myldap/root",
            "user_tree_dn": "ou=Users,dc=root,dc=org"
        }
    }
}

This operation does not accept a request body.

PATCH
/v3/domains/​{domain_id}​/config
Update domain configuration

Updates a domain configuration.

 
Normal response codes
200
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
domain_id URI csapi:UUID

The domain ID.

config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

Response parameters
Parameter Style Type Description
config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

{
    "config": {
        "ldap": {
            "url": "http://myldap/my_new_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
{
    "config": {
        "identity": {
            "driver": "keystone.identity.backends.ldap.Identity"
        },
        "ldap": {
            "url": "http://myldap/my_new_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
DELETE
/v3/domains/​{domain_id}​/config
Delete domain configuration

Deletes a domain configuration.

 
Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/domains/​{domain_id}​/config/​{group}​
Show domain group configuration

Shows details for a domain group configuration.

 

The API supports only the identity and ldap groups.

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

group URI csapi:UUID

The group name, which is ldap or identity.

Response parameters
Parameter Style Type Description
config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

{
    "ldap": {
        "url": "http://myldap/root",
        "user_tree_dn": "ou=Users,dc=root,dc=org"
    }
}

This operation does not accept a request body.

PATCH
/v3/domains/​{domain_id}​/config/​{group}​
Update domain group configuration

Updates a domain group configuration.

 

The API supports only the identity and ldap groups. If you try to set configuration options for other groups, this call fails with the Forbidden (403) response code.

Normal response codes
200
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
domain_id URI csapi:UUID

The domain ID.

group URI csapi:UUID

The group name, which is ldap or identity.

config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver (Optional) plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url (Optional) plain xsd:string

The LDAP URL.

user_tree_dn (Optional) plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

Response parameters
Parameter Style Type Description
config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

{
    "config": {
        "ldap": {
            "url": "http://myldap/my_new_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
{
    "config": {
        "identity": {
            "driver": "keystone.identity.backends.ldap.Identity"
        },
        "ldap": {
            "url": "http://myldap/my_new_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
DELETE
/v3/domains/​{domain_id}​/config/​{group}​
Delete domain group configuration

Deletes a domain group configuration.

 

The API supports only the identity and ldap groups.

Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

group URI csapi:UUID

The group name, which is ldap or identity.

This operation does not accept a request body and does not return a response body.

GET
/v3/domains/​{domain_id}​/config/​{group}​/​{option}​
Show domain group option configuration

Shows details for a domain group option configuration.

 

The API supports only the identity and ldap groups. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

group URI csapi:UUID

The group name, which is ldap or identity.

option URI csapi:UUID

The option name. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Response parameters
Parameter Style Type Description
config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

{
    "url": "http://myldap/root"
}

This operation does not accept a request body.

PATCH
/v3/domains/​{domain_id}​/config/​{group}​/​{option}​
Update domain group option configuration

Updates a domain group option configuration.

 

The API supports only the identity and ldap groups. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Normal response codes
200
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
domain_id URI csapi:UUID

The domain ID.

group URI csapi:UUID

The group name, which is ldap or identity.

option URI csapi:UUID

The option name. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver (Optional) plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url (Optional) plain xsd:string

The LDAP URL.

user_tree_dn (Optional) plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

Response parameters
Parameter Style Type Description
config plain xsd:dict

A config object.

identity plain xsd:dict

An identity object. Required to set the identity group configuration options.

driver plain xsd:string

The Identity back-end driver.

ldap plain xsd:dict

An ldap object. Required to set the LDAP group configuration options.

url plain xsd:string

The LDAP URL.

user_tree_dn plain xsd:string

The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.

{
    "url": "http://myldap/my_other_root"
}
{
    "config": {
        "identity": {
            "driver": "keystone.identity.backends.ldap.Identity"
        },
        "ldap": {
            "url": "http://myldap/my_other_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
DELETE
/v3/domains/​{domain_id}​/config/​{group}​/​{option}​
Delete domain group option configuration

Deletes a domain group option configuration.

 

The API supports only the identity and ldap groups. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

group URI csapi:UUID

The group name, which is ldap or identity.

option URI csapi:UUID

The option name. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

This operation does not accept a request body and does not return a response body.

Groups (groups, users)

A group is a collection of users. Each group is owned by a domain.

When you grant a role to a group, you explicitly associate that group with a project or domain. This action is equivalent to granting the role to each group member on that project and domain.

When you grant a role to a group, that role is automatically granted to any user that you add to the group. When you revoke a role from a group, that role is automatically revoked from any user that you remove from the group. Any token that authenticates that user, project, and domain is revoked.

As with users, a group without any role grants is useless from the perspective an OpenStack service and has no access to resources. However, a group without role grants is permitted as a way of acquiring or loading users and groups from external sources before mapping them to projects and domains.

POST
/v3/groups
Create group

Creates a group.

 
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
group plain xsd:dict

A group object.

name plain xsd:string

The group name.

description (Optional) plain xsd:string

The group description.

domain_id (Optional) plain csapi:UUID

The ID of the domain that owns the group.

If you omit the domain ID, defaults to the domain to which the client token is scoped.

Response parameters
Parameter Style Type Description
group plain xsd:dict

A group object.

domain_id plain csapi:UUID

The ID of the domain for the group.

description plain xsd:string

The group description.

id plain csapi:UUID

The ID for the group.

links plain xsd:dict

The links for the group resource.

name plain xsd:string

The name of the group.

{
    "group": {
        "description": "Contract developers",
        "domain_id": "default",
        "name": "Contract developers"
    }
}
{
    "group": {
        "domain_id": "default",
        "description": "Contract developers",
        "id": "c0d675eac29945ad9dfd08aa1bb75751",
        "links": {
            "self": "http://localhost:5000/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"
        },
        "name": "Contract developers"
    }
}
GET
/v3/groups
List groups

Lists groups.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id (Optional) query csapi:UUID

Filters the response by a domain ID.

name (Optional) query xsd:string

Filters the response by a group name.

Response parameters
Parameter Style Type Description
links (Optional) plain xsd:dict

Links to the groups resource.

groups plain xsd:list

A groups object.

domain_id plain csapi:UUID

The ID of the domain for the group.

description plain xsd:string

The group description.

id plain csapi:UUID

The ID for the group.

links plain xsd:dict

The links for the group resource.

name plain xsd:string

The name of the group.

{
    "links": {
        "self": "http://localhost:5000/v3/groups",
        "previous": null,
        "next": null
    },
    "groups": [
        {
            "domain_id": "default",
            "description": "non-admin group",
            "id": "96372bbb152f475aa37e9a76a25a029c",
            "links": {
                "self": "http://localhost:5000/v3/groups/96372bbb152f475aa37e9a76a25a029c"
            },
            "name": "nonadmins"
        },
        {
            "domain_id": "default",
            "description": "openstack admin group",
            "id": "9ce0ad4e58a84d7a97b92f7955d10c92",
            "links": {
                "self": "http://localhost:5000/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92"
            },
            "name": "admins"
        }
    ]
}
GET
/v3/groups/​{group_id}​
Show group details

Shows details for a group.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
group_id URI csapi:UUID

The group ID.

Response parameters
Parameter Style Type Description
group plain xsd:dict

A group object.

domain_id plain csapi:UUID

The ID of the domain for the group.

description plain xsd:string

The group description.

id plain csapi:UUID

The ID for the group.

links plain xsd:dict

The links for the group resource.

name plain xsd:string

The name of the group.

{
    "group": {
        "domain_id": "default",
        "description": "Contract developers",
        "id": "c0d675eac29945ad9dfd08aa1bb75751",
        "links": {
            "self": "http://localhost:5000/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"
        },
        "name": "Contract developers"
    }
}

This operation does not accept a request body.

PATCH
/v3/groups/​{group_id}​
Update group

Updates a group.

 

If the back-end driver does not support this functionality, the call returns the Not Implemented (501) response code.

Normal response codes
200
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
group_id URI csapi:UUID

The group ID.

group plain xsd:dict

A group object.

name (Optional) plain xsd:string

The group name.

description (Optional) plain xsd:string

The group description.

domain_id (Optional) plain csapi:UUID

The ID of the domain that owns the group.

If you omit the domain ID, defaults to the domain to which the client token is scoped.

Response parameters
Parameter Style Type Description
group plain xsd:dict

A group object.

domain_id plain csapi:UUID

The ID of the domain for the group.

description plain xsd:string

The group description.

id plain csapi:UUID

The ID for the group.

links plain xsd:dict

The links for the group resource.

name plain xsd:string

The name of the group.

{
    "group": {
        "description": "Contract developers 2016",
        "name": "Contract developers 2016"
    }
}
{
    "group": {
        "domain_id": "default",
        "description": "Contract developers 2016",
        "id": "c0d675eac29945ad9dfd08aa1bb75751",
        "links": {
            "self": "http://localhost:5000/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"
        },
        "name": "Contract developers 2016"
    }
}
DELETE
/v3/groups/​{group_id}​
Delete group

Deletes a group.

 
Normal response codes
204
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
group_id URI csapi:UUID

The group ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/groups/​{group_id}​/users
List users in group

Lists the users that belong to a group.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
group_id URI csapi:UUID

The group ID.

domain_id (Optional) query csapi:UUID

Filters the response by a domain ID.

description (Optional) query xsd:string

Filters the response by a description.

name (Optional) query xsd:string

Filters the response by a group name.

enabled (Optional) query xsd:string

Filters the response by either enabled (true) or disabled (false) groups.

Response parameters
Parameter Style Type Description
users plain xsd:list

A users object.

name plain xsd:string

The user name. Must be unique within the domain.

links plain xsd:dict

The links for the user resource.

domain_id plain csapi:UUID

The ID of the domain for the user.

enabled plain xsd:boolean

If the user is enabled, this value is true. If the user is disabled, this value is false.

email plain xsd:string

The email address for the user.

id plain csapi:UUID

The ID for the user.

links plain xsd:dict

The links for the users resource.

{
    "users": [
        {
            "name": "admin",
            "links": {
                "self": "http://localhost:5000/v3/users/fff603a0829d41e48bc0dd0d72ad61ce"
            },
            "domain_id": "default",
            "enabled": true,
            "email": null,
            "id": "fff603a0829d41e48bc0dd0d72ad61ce"
        }
    ],
    "links": {
        "self": "http://localhost:5000/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92/users",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/groups/​{group_id}​/users/​{user_id}​
Add user to group

Adds a user to a group.

 
Normal response codes
204
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
group_id URI csapi:UUID

The group ID.

user_id URI csapi:UUID

The user ID.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/groups/​{group_id}​/users/​{user_id}​
Check whether user belongs to group

Validates that a user belongs to a group.

 
Normal response codes
204
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
group_id URI csapi:UUID

The group ID.

user_id URI csapi:UUID

The user ID.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/groups/​{group_id}​/users/​{user_id}​
Remove user from group

Removes a user from a group.

 
Normal response codes
204
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
group_id URI csapi:UUID

The group ID.

user_id URI csapi:UUID

The user ID.

This operation does not accept a request body and does not return a response body.

Policies (policies)

A policy is an arbitrarily serialized policy engine rule set to be consumed by a remote service.

You encode policy rule sets into a blob that remote services can consume. To do so, set type to application/json and specify policy rules as JSON strings in a blob. For example:

{
    "blob":{
        "foobar_user":[
            "role:compute-user"
        ]
    }
}
POST
/v3/policies
Create policy

Creates a policy.

 
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
policy plain xsd:dict

A policy object.

blob plain xsd:string

The policy rule set itself, as a serialized blob.

type plain xsd:string

The MIME media type of the serialized policy blob.

project_id (Optional) plain csapi:UUID

The UUID for the associated project.

user_id (Optional) plain csapi:UUID

The ID of the user who owns the policy.

Response parameters
Parameter Style Type Description
policy plain xsd:dict

A policy object.

blob plain xsd:string

The policy rule set itself, as a serialized blob.

id plain csapi:UUID

The ID of the policy.

links plain csapi:dict

The links for the policy resource.

type plain xsd:string

The MIME media type of the serialized policy blob.

project_id (Optional) plain csapi:UUID

The UUID for the associated project.

user_id (Optional) plain csapi:UUID

The ID of the user who owns the policy.

{
    "policy": {
        "blob": "{'foobar_user': 'role:compute-user'}",
        "project_id": "0426ac1e48f642ef9544c2251e07e261",
        "type": "application/json",
        "user_id": "0ffd248c55b443eaac5253b4e9cbf9b5"
    }
}
{
    "policy": {
        "user_id": "0ffd248c55b443eaac5253b4e9cbf9b5",
        "links": {
            "self": "http://identity:35357/v3/policies/88f5b83f8f8e41daba4c25eed1a7bbc6"
        },
        "blob": "{'foobar_user': 'role:compute-user'}",
        "project_id": "0426ac1e48f642ef9544c2251e07e261",
        "type": "application/json",
        "id": "88f5b83f8f8e41daba4c25eed1a7bbc6"
    }
}
GET
/v3/policies
List policies

Lists policies.

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

Filters the response by a MIME media type for the serialized policy blob. For example, application/json.

Response parameters
Parameter Style Type Description
policies plain xsd:list

A policies object.

links plain csapi:dict

The links for the policies resource.

blob plain xsd:dict

The policy rule itself, as a serialized blob.

id plain csapi:UUID

The ID of the policy.

links plain csapi:dict

The links for the policy resource.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The MIME media type of the serialized policy blob.

user_id plain csapi:UUID

The ID of the user who owns the policy.

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/policies"
    },
    "policies": [
        {
            "blob": {
                "foobar_user": [
                    "role:compute-user"
                ]
            },
            "id": "717273",
            "links": {
                "self": "http://identity:35357/v3/policies/717273"
            },
            "project_id": "456789",
            "type": "application/json",
            "user_id": "616263"
        },
        {
            "blob": {
                "foobar_user": [
                    "role:compute-user"
                ]
            },
            "id": "717274",
            "links": {
                "self": "http://identity:35357/v3/policies/717274"
            },
            "project_id": "456789",
            "type": "application/json",
            "user_id": "616263"
        }
    ]
}
GET
/v3/policies/​{policy_id}​
Show policy details

Shows details for a policy.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
policy_id URI csapi:UUID

The policy ID.

Response parameters
Parameter Style Type Description
policy plain xsd:dict

A policy object.

blob plain xsd:dict

The policy rule itself, as a serialized blob.

id plain csapi:UUID

The ID of the policy.

links plain csapi:dict

The links for the policy resource.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The MIME media type of the serialized policy blob.

user_id plain csapi:UUID

The ID of the user who owns the policy.

{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "id": "717273",
        "links": {
            "self": "http://identity:35357/v3/policies/717273"
        },
        "project_id": "456789",
        "type": "application/json",
        "user_id": "616263"
    }
}

This operation does not accept a request body.

PATCH
/v3/policies/​{policy_id}​
Update policy

Updates a policy.

 
Normal response codes
200
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
policy_id URI csapi:UUID

The policy ID.

policy plain xsd:dict

A policy object.

blob plain xsd:dict

The policy rule itself, as a serialized blob.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The MIME media type of the serialized policy blob.

user_id plain csapi:UUID

The ID of the user who owns the policy.

Response parameters
Parameter Style Type Description
policy plain xsd:dict

A policy object.

blob plain xsd:dict

The policy rule itself, as a serialized blob.

id plain csapi:UUID

The ID of the policy.

links plain csapi:dict

The links for the policy resource.

project_id plain csapi:UUID

The UUID for the associated project.

type plain xsd:string

The MIME media type of the serialized policy blob.

user_id plain csapi:UUID

The ID of the user who owns the policy.

{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "project_id": "456789",
        "type": "application/json",
        "user_id": "616263"
    }
}
{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "id": "717273",
        "links": {
            "self": "http://identity:35357/v3/policies/717273"
        },
        "project_id": "456789",
        "type": "application/json",
        "user_id": "616263"
    }
}
DELETE
/v3/policies/​{policy_id}​
Delete policy

Deletes a policy.

 
Normal response codes
204
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
policy_id URI csapi:UUID

The policy ID.

This operation does not accept a request body and does not return a response body.

Projects (projects, users, groups, roles)

A project is the base unit of ownership. Resources are owned by a specific project. A project is owned by a specific domain.

(Since v3.4) You can create a hierarchy of projects by setting a parent ID when you create projects. All projects in a hierarchy must be owned by the same domain.

(Since v3.6) Optionally, you can create a project that behaves both as a project and a domain. As a domain, the project provides a name space in which you can create users, groups, and other projects. If you create a project that behaves as a domain, you cannot update this project to behave like a regular project.

GET
/v3/projects
List projects

Lists projects.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id (Optional) query csapi:UUID

Filters the response by a domain ID.

parent_id (Optional) query csapi:UUID

(Since v3.4) Filters the response by a parent ID.

name (Optional) query xsd:string

Filters the response by a project name.

enabled (Optional) query xsd:string

Filters the response by either enabled (true) or disabled (false) projects.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the projects resource.

projects plain xsd:list

A projects object.

description plain xsd:string

The project description.

domain_id plain csapi:UUID

The ID of the domain for the project.

enabled plain xsd:boolean

If set to true, project is enabled. If set to false, project is disabled.

id plain csapi:UUID

The ID for the project.

is_domain (Optional) plain xsd:boolean

(Since v3.6) Indicates whether the project also acts as a domain.

If set to true, this project acts as both a project and domain. As a domain, the project provides a name space in which you can create users, groups, and other projects.

Otherwise, this field does not appear in the response and this project behaves as a regular project that contains only resources.

links plain xsd:dict

The links for the project resource.

name plain xsd:string

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

parent_id plain csapi:UUID

(Since v3.4) The ID of the parent project. If null, the project is a top-level project.

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/projects"
    },
    "projects": [
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "0c4e939acacf4376bdcd1129f1a054ad",
            "links": {
                "self": "http://localhost:5000/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
            },
            "name": "admin",
            "parent_id": null
        },
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "0cbd49cbf76d405d9c86562e1d579bd3",
            "links": {
                "self": "http://localhost:5000/v3/projects/0cbd49cbf76d405d9c86562e1d579bd3"
            },
            "name": "demo",
            "parent_id": null
        },
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "2db68fed84324f29bb73130c6c2094fb",
            "links": {
                "self": "http://localhost:5000/v3/projects/2db68fed84324f29bb73130c6c2094fb"
            },
            "name": "swifttenanttest2",
            "parent_id": null
        },
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "3d594eb0f04741069dbbb521635b21c7",
            "links": {
                "self": "http://localhost:5000/v3/projects/3d594eb0f04741069dbbb521635b21c7"
            },
            "name": "service",
            "parent_id": null
        },
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "43ebde53fc314b1c9ea2b8c5dc744927",
            "links": {
                "self": "http://localhost:5000/v3/projects/43ebde53fc314b1c9ea2b8c5dc744927"
            },
            "name": "swifttenanttest1",
            "parent_id": null
        },
        {
            "description": "",
            "domain_id": "1bc2169ca88e4cdaaba46d4c15390b65",
            "enabled": true,
            "id": "4b1eb781a47440acb8af9850103e537f",
            "links": {
                "self": "http://localhost:5000/v3/projects/4b1eb781a47440acb8af9850103e537f"
            },
            "name": "swifttenanttest4",
            "parent_id": null
        },
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "5961c443439d4fcebe42643723755e9d",
            "links": {
                "self": "http://localhost:5000/v3/projects/5961c443439d4fcebe42643723755e9d"
            },
            "name": "invisible_to_admin",
            "parent_id": null
        },
        {
            "description": null,
            "domain_id": "default",
            "enabled": true,
            "id": "fdb8424c4e4f4c0ba32c52e2de3bd80e",
            "links": {
                "self": "http://localhost:5000/v3/projects/fdb8424c4e4f4c0ba32c52e2de3bd80e"
            },
            "name": "alt_demo",
            "parent_id": null
        }
    ]
}
POST
/v3/projects
Create project

Creates a project.

 
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
project plain xsd:dict

A project object.

description (Optional) plain xsd:string

The project description.

domain_id (Optional) plain csapi:UUID

The ID of the domain for the project.

If you omit the domain ID, default is the domain to which your token is scoped.

enabled (Optional) plain xsd:boolean

Enables or disables the project.

Users can authorize against an enabled project.

Users cannot authorize against a disabled project. All tokens that are authorized for a disabled project become no longer valid. If you reenable the project, these tokens are not re-enabled.

To enable the project, set to true. To disable the project, set to false. Default is true.

is_domain (Optional) plain xsd:boolean

(Since v3.6) Indicates whether the project also acts as a domain.

Set to true to define this project as both a project and domain. As a domain, the project provides a name space in which you can create users, groups, and other projects.

Set to false to define this project as a regular project that contains only resources.

Default is false.

You cannot update this parameter after you create the project.

name plain xsd:string

The project name, which must be unique within the owning domain. The project can have the same name as its domain.

parent_id (Optional) plain csapi:UUID

(Since v3.4) The ID of the parent project.

If you omit the parent project ID, the project is a top-level project.

Response parameters
Parameter Style Type Description
project plain xsd:dict

A project object.

is_domain (Optional) plain xsd:boolean

(Since v3.6) Indicates whether the project also acts as a domain.

If set to true, this project acts as both a project and domain. As a domain, the project provides a name space in which you can create users, groups, and other projects.

Otherwise, this field does not appear in the response and this project behaves as a regular project that contains only resources.

description plain xsd:string

The project description.

links plain xsd:dict

The links for the project resource.

enabled plain xsd:boolean

If set to true, project is enabled. If set to false, project is disabled.

id plain csapi:UUID

The ID for the project.

parent_id plain csapi:UUID

(Since v3.4) The ID of the parent project. If null, the project is a top-level project.

domain_id plain csapi:UUID

The ID of the domain for the project.

name plain xsd:string

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

{
    "project": {
        "description": "My new project",
        "domain_id": "default",
        "enabled": true,
        "is_domain": true,
        "name": "myNewProject"
    }
}
{
    "project": {
        "is_domain": true,
        "description": "My new project",
        "links": {
            "self": "http://localhost:5000/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
        },
        "enabled": true,
        "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
        "parent_id": null,
        "domain_id": "default",
        "name": "myNewProject"
    }
}
GET
/v3/projects/​{project_id}​
Show project details

Shows details for a project.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
project_id URI csapi:UUID

The project ID.

Response parameters
Parameter Style Type Description
project plain xsd:dict

A project object.

is_domain (Optional) plain xsd:boolean

(Since v3.6) Indicates whether the project also acts as a domain.

If set to true, this project acts as both a project and domain. As a domain, the project provides a name space in which you can create users, groups, and other projects.

Otherwise, this field does not appear in the response and this project behaves as a regular project that contains only resources.

description plain xsd:string

The project description.

links plain xsd:dict

The links for the project resource.

enabled plain xsd:boolean

If set to true, project is enabled. If set to false, project is disabled.

id plain csapi:UUID

The ID for the project.

parent_id plain csapi:UUID

(Since v3.4) The ID of the parent project. If null, the project is a top-level project.

domain_id plain csapi:UUID

The ID of the domain for the project.

name plain xsd:string

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

{
    "project": {
        "description": null,
        "domain_id": "default",
        "enabled": true,
        "id": "0c4e939acacf4376bdcd1129f1a054ad",
        "links": {
            "self": "http://localhost:5000/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
        },
        "name": "admin",
        "parent_id": null
    }
}

This operation does not accept a request body.

PATCH
/v3/projects/​{project_id}​
Update project

Updates a project.

 
Normal response codes
200
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
project_id URI csapi:UUID

The project ID.

project plain xsd:dict

A project object.

description (Optional) plain xsd:string

The project description.

domain_id (Optional) plain csapi:UUID

The ID of the domain for the project.

If you omit the domain ID, default is the domain to which your token is scoped.

enabled (Optional) plain xsd:boolean

Enables or disables the project.

Users can authorize against an enabled project.

Users cannot authorize against a disabled project. All tokens that are authorized for a disabled project become no longer valid. If you reenable the project, these tokens are not re-enabled.

To enable the project, set to true. To disable the project, set to false. Default is true.

name plain xsd:string

The project name, which must be unique within the owning domain. The project can have the same name as its domain.

parent_id (Optional) plain csapi:UUID

(Since v3.4) The ID of the parent project.

If you omit the parent project ID, the project is a top-level project.

Response parameters
Parameter Style Type Description
project plain xsd:dict

A project object.

is_domain (Optional) plain xsd:boolean

(Since v3.6) Indicates whether the project also acts as a domain.

If set to true, this project acts as both a project and domain. As a domain, the project provides a name space in which you can create users, groups, and other projects.

Otherwise, this field does not appear in the response and this project behaves as a regular project that contains only resources.

description plain xsd:string

The project description.

links plain xsd:dict

The links for the project resource.

enabled plain xsd:boolean

If set to true, project is enabled. If set to false, project is disabled.

id plain csapi:UUID

The ID for the project.

parent_id plain csapi:UUID

(Since v3.4) The ID of the parent project. If null, the project is a top-level project.

domain_id plain csapi:UUID

The ID of the domain for the project.

name plain xsd:string

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

{
    "project": {
        "description": "My updated project",
        "domain_id": "default",
        "enabled": true,
        "name": "myUpdatedProject"
    }
}
{
    "project": {
        "is_domain": true,
        "description": "My updated project",
        "links": {
            "self": "http://localhost:5000/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
        },
        "extra": {
            "is_domain": true
        },
        "enabled": true,
        "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
        "parent_id": null,
        "domain_id": "default",
        "name": "myUpdatedProject"
    }
}
DELETE
/v3/projects/​{project_id}​
Delete project

Deletes a project.

 
Normal response codes
204
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
project_id URI csapi:UUID

The project ID.

This operation does not accept a request body and does not return a response body.

PATCH
/v3/projects/​{project_id}​/cascade
Enable or disable project and its subtree

(Since v3.6) Enables or disables a project and its entire subtree.

 

A project subtree includes all projects beneath the parent project in the hierarchy.

If you include attributes other than the enabled attribute, this call fails and returns the Bad Request (400) response code.

If you perform this action against a project that acts as a domain (is_domain is set to true, this call fails and returns the Forbidden (403) response code.

Normal response codes
200
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
project_id URI csapi:UUID

The project ID.

project plain xsd:dict

A project object.

enabled plain xsd:boolean

Enables or disables the project and its subtree.

Users can authorize against an enabled project.

Users cannot authorize against a disabled project. All tokens that are authorized for a disabled project become no longer valid. If you reenable the project, these tokens are not re-enabled.

To enable the project and its subtree, set to true. To disable the project and its subtree, set to false. Default is true.

Response parameters
Parameter Style Type Description
project plain xsd:dict

A project object.

is_domain (Optional) plain xsd:boolean

(Since v3.6) Indicates whether the project also acts as a domain.

If set to true, this project acts as both a project and domain. As a domain, the project provides a name space in which you can create users, groups, and other projects.

Otherwise, this field does not appear in the response and this project behaves as a regular project that contains only resources.

description plain xsd:string

The project description.

links plain xsd:dict

The links for the project resource.

enabled plain xsd:boolean

If set to true, project is enabled. If set to false, project is disabled.

id plain csapi:UUID

The ID for the project.

parent_id plain csapi:UUID

(Since v3.4) The ID of the parent project. If null, the project is a top-level project.

domain_id plain csapi:UUID

The ID of the domain for the project.

name plain xsd:string

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

{
    "project": {
        "enabled": true
    }
}
{
    "project": {
        "is_domain": true,
        "description": "My updated project",
        "links": {
            "self": "http://localhost:5000/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
        },
        "extra": {
            "is_domain": true
        },
        "enabled": true,
        "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
        "parent_id": null,
        "domain_id": "default",
        "name": "myUpdatedProject"
    }
}
DELETE
/v3/projects/​{project_id}​/cascade
Delete project subtree

(Since v3.6) Deletes a project and its entire subtree.

 

A project subtree includes all projects beneath the parent project in the hierarchy. You must disable the projects in the subtree before you perform this operation.

Normal response codes
204
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
project_id URI csapi:UUID

The project ID.

This operation does not accept a request body and does not return a response body.

Regions (regions) (since v3.2)

A region is a general division of an OpenStack deployment. You can associate zero or more sub-regions with a region to create a tree-like structured hierarchy.

Although a region does not have a geographical connotation, a deployment can use a geographical name for a region, such as us-east.

You can list, create, update, show details for, and delete regions.

GET
/v3/regions
List regions

Lists regions.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
parent_region_id (Optional) query csapi:UUID

Filters the response by a parent region, by ID.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the regions resource.

regions plain xsd:list

A regions object.

description plain xsd:string

The region description.

id plain csapi:UUID

The ID for the region.

links plain xsd:dict

The links for the region resource.

parent_region_id plain csapi:UUID

If the region is a child of another region, the ID for the parent region. Otherwise, this value is null.

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/regions"
    },
    "regions": [
        {
            "description": "",
            "id": "RegionOne",
            "links": {
                "self": "http://localhost:5000/v3/regions/RegionOne"
            },
            "parent_region_id": null
        }
    ]
}
POST
/v3/regions
Create region

Creates a region.

 

When you create the region, you can optionally specify a region ID. If you include characters in the region ID that are not allowed in a URI, you must URL-encode the ID. If you omit an ID, the API assigns an ID to the region.

The following errors might occur:

  • Not Found (404). The parent region ID does not exist.

  • Conflict (409). The parent region ID would form a circular relationship.

  • Conflict (409). The user-defined region ID is not unique to the OpenStack deployment.

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
region plain xsd:dict

A region object.

description (Optional) plain xsd:string

The region description.

id (Optional) plain csapi:UUID

A user-defined region ID.

If you include characters in the region ID that are not allowed in a URI, you must URL-encode the ID. If you omit an ID, the API assigns an ID to the region.

parent_region_id (Optional) plain csapi:UUID

To make this region a child of another region, set this parameter to the ID of the parent region.

Response parameters
Parameter Style Type Description
region plain xsd:dict

A region object.

description plain xsd:string

The region description.

id plain csapi:UUID

The ID for the region.

links plain xsd:dict

The links for the region resource.

parent_region_id plain csapi:UUID

If the region is a child of another region, the ID for the parent region. Otherwise, this value is null.

{
    "region": {
        "description": "My subregion",
        "id": "RegionOneSubRegion",
        "parent_region_id": "RegionOne"
    }
}
{
    "region": {
        "parent_region_id": "RegionOne",
        "id": "RegionOneSubRegion",
        "links": {
            "self": "http://localhost:5000/v3/regions/RegionOneSubRegion"
        },
        "description": "My subregion"
    }
}
GET
/v3/regions/​{region_id}​
Show region details

Shows details for a region, by ID.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
region_id URI csapi:UUID

The region ID.

Response parameters
Parameter Style Type Description
region plain xsd:dict

A region object.

description plain xsd:string

The region description.

id plain csapi:UUID

The ID for the region.

links plain xsd:dict

The links for the region resource.

parent_region_id plain csapi:UUID

If the region is a child of another region, the ID for the parent region. Otherwise, this value is null.

{
    "region": {
        "description": "My subregion 3",
        "id": "RegionThree",
        "links": {
            "self": "http://localhost:5000/v3/regions/RegionThree"
        },
        "parent_region_id": "RegionOne"
    }
}

This operation does not accept a request body.

PATCH
/v3/regions/​{region_id}​
Update region

Updates a region.

 

You can update the description or parent region ID for a region. You cannot update the region ID.

The following error might occur:

  • Not Found (404). The parent region ID does not exist.

Normal response codes
200
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
region_id URI csapi:UUID

The region ID.

region plain xsd:dict

A region object.

description (Optional) plain xsd:string

The region description.

parent_region_id (Optional) plain csapi:UUID

To make this region a child of another region, set this parameter to the ID of the parent region.

Response parameters
Parameter Style Type Description
region plain xsd:dict

A region object.

description plain xsd:string

The region description.

id plain csapi:UUID

The ID for the region.

links plain xsd:dict

The links for the region resource.

parent_region_id plain csapi:UUID

If the region is a child of another region, the ID for the parent region. Otherwise, this value is null.

{
    "region": {
        "description": "My subregion 3"
    }
}
{
    "region": {
        "parent_region_id": "RegionOne",
        "id": "RegionThree",
        "links": {
            "self": "http://localhost:5000/v3/regions/RegionThree"
        },
        "description": "My subregion 3"
    }
}
DELETE
/v3/regions/​{region_id}​
Delete region

Deletes a region.

 

The following error might occur:

  • Conflict (409). The region cannot be deleted because it has child regions.

Normal response codes
204
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
region_id URI csapi:UUID

The region ID.

This operation does not accept a request body and does not return a response body.

Roles (roles)

Roles grant a user a set of permitted actions for either a specific project or an entire domain.

You can grant roles to a user on a project, including projects owned by other domains.

You can create, list, and delete roles. You can also list roles assigned to a specified domain, project, or user.

You can list role assignments and, since v3.6, all role assignments within a tree of projects. Use the query parameters to filter the list because the role assignments list can be long. Some typical examples are:

  • List role assignments for the specified user:

    GET /role_assignments?user.id={user_id}

  • List role assignments for the specified project:

    GET /role_assignments?scope.project.id={project_id}

  • List all role assignments for a specified project and its sub- projects:

    GET /role_assignments?scope.project.id={project_id}?include_subtree=true

    If you specify include_subtree=true, you must also specify the scope.project.id. Otherwise, this call returns the Bad Request (400) response code.

Each role assignment entity in the collection contains a link to the assignment that created the entity.

Use the effective query parameter to list effective assignments at the user, project, and domain level. This parameter allows for the effects of group membership. The group role assignment entities themselves are not returned in the collection. This represents the effective role assignments that would be included in a scoped token.

In the response, the links entity section for entities for group members also contains a URL that enables access to the membership of the group.

You can use the other query parameters with the effective parameter, such as:

  • Determine what a user can actually do:

    GET /role_assignments?user.id={user_id}&effective

  • Get the equivalent set of role assignments that are included in a project-scoped token response:

    GET /role_assignments?user.id={user_id}&scope.project.id={project_id}&effective

POST
/v3/roles
Create role

Creates a role.

 
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
role plain xsd:dict

A role object.

name plain xsd:string

The role name.

Response parameters
Parameter Style Type Description
role plain xsd:dict

A role object.

id plain csapi:UUID

The role ID.

links plain xsd:dict

The links for the role resource.

name plain xsd:string

The role name.

{
    "role": {
        "name": "developer"
    }
}
{
    "role": {
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://localhost:5000/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "name": "developer"
    }
}
GET
/v3/roles
List roles

Lists roles.

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

Filters the response by a role name.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the roles resource.

roles plain xsd:list

A roles object.

id plain csapi:UUID

The role ID.

links plain xsd:dict

The links for the role resource.

name plain xsd:string

The role name.

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/roles"
    },
    "roles": [
        {
            "id": "5318e65d75574c17bf5339d3df33a5a3",
            "links": {
                "self": "http://localhost:5000/v3/roles/5318e65d75574c17bf5339d3df33a5a3"
            },
            "name": "admin"
        },
        {
            "id": "642bcfc75c384fd181adf34d9b2df897",
            "links": {
                "self": "http://localhost:5000/v3/roles/642bcfc75c384fd181adf34d9b2df897"
            },
            "name": "anotherrole"
        },
        {
            "id": "779a76d74f544224a7ef8762ca0de627",
            "links": {
                "self": "http://localhost:5000/v3/roles/779a76d74f544224a7ef8762ca0de627"
            },
            "name": "Member"
        },
        {
            "id": "9fe2ff9ee4384b1894a90878d3e92bab",
            "links": {
                "self": "http://localhost:5000/v3/roles/9fe2ff9ee4384b1894a90878d3e92bab"
            },
            "name": "_member_"
        },
        {
            "id": "ba2dfba61c934ee89e3110de36273229",
            "links": {
                "self": "http://localhost:5000/v3/roles/ba2dfba61c934ee89e3110de36273229"
            },
            "name": "ResellerAdmin"
        },
        {
            "id": "f127b97616f24d3ebceb7be840210adc",
            "links": {
                "self": "http://localhost:5000/v3/roles/f127b97616f24d3ebceb7be840210adc"
            },
            "name": "service"
        }
    ]
}
GET
/v3/roles/​{role_id}​
Show role details

Shows details for a role.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
role_id URI csapi:UUID

The role ID.

Response parameters
Parameter Style Type Description
role plain xsd:dict

A role object.

id plain csapi:UUID

The role ID.

links plain xsd:dict

The links for the role resource.

name plain xsd:string

The role name.

{
    "role": {
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://localhost:5000/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "name": "Developer"
    }
}

This operation does not accept a request body.

PATCH
/v3/roles/​{role_id}​
Update role

Updates a role.

 
Normal response codes
200
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
role_id URI csapi:UUID

The role ID.

role plain xsd:dict

A role object.

name plain xsd:string

The role name.

Response parameters
Parameter Style Type Description
role plain xsd:dict

A role object.

id plain csapi:UUID

The role ID.

links plain xsd:dict

The links for the role resource.

name plain xsd:string

The role name.

{
    "role": {
        "name": "Developer"
    }
}
{
    "role": {
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://localhost:5000/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "name": "Developer"
    }
}
DELETE
/v3/roles/​{role_id}​
Delete role

Deletes a role.

 
Normal response codes
204
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
role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/domains/​{domain_id}​/users/​{user_id}​/roles
List roles for user on domain

Lists roles for a user on a domain.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

user_id URI csapi:UUID

The user ID.

Response parameters
Parameter Style Type Description
roles plain xsd:list

A roles object.

id plain csapi:UUID

The role ID.

links plain xsd:dict

The links for the role resource.

name plain xsd:string

The role name.

links plain xsd:dict

The links for the roles resource.

{
    "roles": [
        {
            "id": "123456",
            "links": {
                "self": "http://identity:35357/v3/roles/123456"
            },
            "name": "admin"
        },
        {
            "id": "123457",
            "links": {
                "self": "http://identity:35357/v3/roles/123457"
            },
            "name": "manager"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/domains/161718/users/313233/roles",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/domains/​{domain_id}​/users/​{user_id}​/roles/​{role_id}​
Grant role to user on domain

Grants a role to a user on a domain.

 
Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

user_id URI csapi:UUID

The user ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/domains/​{domain_id}​/users/​{user_id}​/roles/​{role_id}​
Check whether user has role on domain

Validates that a user has a role on a domain.

 
Normal response codes
204
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

user_id URI csapi:UUID

The user ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/domains/​{domain_id}​/users/​{user_id}​/roles/​{role_id}​
Revoke role from user on domain

Revokes a role from a user on a domain.

 
Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

user_id URI csapi:UUID

The user ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/domains/​{domain_id}​/groups/​{group_id}​/roles
List roles for group on domain

Lists roles for a group on a domain.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

group_id URI csapi:UUID

The group ID.

{
    "roles": [
        {
            "id": "123456",
            "links": {
                "self": "http://identity:35357/v3/roles/123456"
            },
            "name": "admin"
        },
        {
            "id": "123457",
            "links": {
                "self": "http://identity:35357/v3/roles/123457"
            },
            "name": "manager"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/domains/161718/groups/101112/roles",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/domains/​{domain_id}​/groups/​{group_id}​/roles/​{role_id}​
Grant role to group on domain

Grants a role to a group on a domain.

 
Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

group_id URI csapi:UUID

The group ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/domains/​{domain_id}​/groups/​{group_id}​/roles/​{role_id}​
Check whether group has role on domain

Validates that a group has a role on a domain.

 
Normal response codes
204
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
domain_id URI csapi:UUID

The domain ID.

group_id URI csapi:UUID

The group ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/domains/​{domain_id}​/groups/​{group_id}​/roles/​{role_id}​
Revoke role from group on domain

Revokes a role from a group on a domain.

 
Normal response codes
204
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
domain_id URI csapi:UUID

The domain ID.

group_id URI csapi:UUID

The group ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/projects/​{project_id}​/users/​{user_id}​/roles
List roles for user on project

Lists roles for a user on a project.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
project_id URI csapi:UUID

The project ID.

user_id URI csapi:UUID

The user ID.

{
    "links": {
        "self": "http://localhost:5000/v3/projects/9e5a15e2c0dd42aab0990a463e839ac1/users/b964a9e51c0046a4a84d3f83a135a97c/roles",
        "previous": null,
        "next": null
    },
    "roles": [
        {
            "id": "3b5347fa7a144008ba57c0acea469cc3",
            "links": {
                "self": "http://localhost:5000/v3/roles/3b5347fa7a144008ba57c0acea469cc3"
            },
            "name": "admin"
        }
    ]
}

This operation does not accept a request body.

PUT
/v3/projects/​{project_id}​/users/​{user_id}​/roles/​{role_id}​
Grant role to user on project

Grants a role to a user on a project.

 
Normal response codes
204
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
project_id URI csapi:UUID

The project ID.

user_id URI csapi:UUID

The user ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/projects/​{project_id}​/users/​{user_id}​/roles/​{role_id}​
Check whether user has role on project

Validates that a user has a role on a project.

 
Normal response codes
204
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
project_id URI csapi:UUID

The project ID.

user_id URI csapi:UUID

The user ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/projects/​{project_id}​/users/​{user_id}​/roles/​{role_id}​
Revoke role from user on project

Revokes a role from a user on a project.

 
Normal response codes
204
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
project_id URI csapi:UUID

The project ID.

user_id URI csapi:UUID

The user ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/projects/​{project_id}​/groups/​{group_id}​/roles
List roles for group on project

Lists roles for a group on a project.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
project_id URI csapi:UUID

The project ID.

group_id URI csapi:UUID

The group ID.

{
    "roles": [
        {
            "id": "123456",
            "links": {
                "self": "http://identity:35357/v3/roles/123456"
            },
            "name": "admin"
        },
        {
            "id": "123457",
            "links": {
                "self": "http://identity:35357/v3/roles/123457"
            },
            "name": "manager"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/projects/456789/groups/101112/roles",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/projects/​{project_id}​/groups/​{group_id}​/roles/​{role_id}​
Grant role to group on project

Grants a role to a group on a project.

 
Normal response codes
204
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
project_id URI csapi:UUID

The project ID.

group_id URI csapi:UUID

The group ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/projects/​{project_id}​/groups/​{group_id}​/roles/​{role_id}​
Check whether group has role on project

Validates that a group has a role on a project.

 
Normal response codes
204
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
project_id URI csapi:UUID

The project ID.

group_id URI csapi:UUID

The group ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/projects/​{project_id}​/groups/​{group_id}​/roles/​{role_id}​
Revoke role from group on project

Revokes a role from a group on a project.

 
Normal response codes
204
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
project_id URI csapi:UUID

The project ID.

group_id URI csapi:UUID

The group ID.

role_id URI csapi:UUID

The role ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/role_assignments
List role assignments

Lists role assignments.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
group.id (Optional) query csapi:UUID

Filters the response by a group ID. To list all role assignments for a group, specify group.id={group_id}.

role.id (Optional) query csapi:UUID

Filters the response by a role ID. To list all role assignments for a role, specify role.id={role_id}.

scope.domain.id (Optional) query csapi:UUID

Filters the response by a domain ID. To list all role assignments for a domain, specify scope.domain.id={domain_id}.

scope.project.id (Optional) query csapi:UUID

Filters the response by a project ID. To list all role assignments for a project, specify scope.project.id={project_id}.

user.id (Optional) query csapi:UUID

Filters the response by a user ID. To list all role assignments for a user, specify user.id={user_id}.

effective (Optional) query xsd:key

Lists effective assignments at the user, project, and domain level, allowing for the effects of group membership.

The group role assignment entities themselves are not returned in the collection.

This represents the effective role assignments that would be included in a scoped token. You can use the other query parameters with the effective parameter.

include_subtree (Optional) query xsd:boolean

(Since v3.6) Lists all role assignments within a tree of projects. The following call lists all role assignments for a project and its sub-projects:

GET /role_assignments?scope.project.id={project_id}?include_subtree=true

You can specify include_subtree=true only in combination with scope.project.id. If you do not include the project ID, this call returns the Bad Request (400) response code.

Each role assignment entity in the collection contains a link to the assignment that created the entity.

Response parameters
Parameter Style Type Description
role_assignments plain xsd:list

A role_assignments object.

GET /role_assignments?user.id={user_id}&scope.project.id={project_id}&effective
{
    "role_assignments": [
        {
            "links": {
                "assignment": "http://identity:35357/v3/domains/161718/users/313233/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "domain": {
                    "id": "161718"
                }
            },
            "user": {
                "id": "313233"
            }
        },
        {
            "group": {
                "id": "101112"
            },
            "links": {
                "assignment": "http://identity:35357/v3/projects/456789/groups/101112/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "project": {
                    "id": "456789"
                }
            }
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/role_assignments",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

Service catalog and endpoints (services, endpoints)

A service is an OpenStack web service that you can access through a URL, or endpoint.

A service catalog lists the services that are available to the caller based upon the current authorization.

You can create, list, show details for, update, and delete services. When you create or update a service, you can enable the service, which causes it and its endpoints to appear in the service catalog.

You can create, list, show details for, update, and delete endpoints.

GET
/v3/services
List services

Lists all services.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

type (Optional) query xsd:string

Filters the response by a service type. A valid value is compute, ec2, identity, image, network, or volume.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the services resource.

services plain xsd:list

A services object.

description plain xsd:string

The service description.

enabled plain xsd:boolean

Defines whether the service and its endpoints appear in the service catalog:

  • false. The service and its endpoints do not appear in the service catalog.

  • true. The service and its endpoints appear in the service catalog.

id plain csapi:UUID

The ID of the service.

links plain xsd:dict

The links for the service resource.

name plain xsd:string

The service name.

type plain xsd:string

The service type, which describes the API implemented by the service. Value is compute, ec2, identity, image, network, or volume.

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/services"
    },
    "services": [
        {
            "description": "Nova Compute Service",
            "enabled": true,
            "id": "1999c3a858c7408fb586817620695098",
            "links": {
                "self": "http://localhost:5000/v3/services/1999c3a858c7408fb586817620695098"
            },
            "name": "nova",
            "type": "compute"
        },
        {
            "description": "Cinder Volume Service V2",
            "enabled": true,
            "id": "39216610e75547f1883037e11976fc0f",
            "links": {
                "self": "http://localhost:5000/v3/services/39216610e75547f1883037e11976fc0f"
            },
            "name": "cinderv2",
            "type": "volumev2"
        },
        {
            "description": "Neutron Service",
            "enabled": true,
            "id": "4fe41a27de3341af9100123f765eac0d",
            "links": {
                "self": "http://localhost:5000/v3/services/4fe41a27de3341af9100123f765eac0d"
            },
            "name": "neutron",
            "type": "network"
        },
        {
            "description": "EC2 Compatibility Layer",
            "enabled": true,
            "id": "61d3d05bdd1449f18923c83f52a4d762",
            "links": {
                "self": "http://localhost:5000/v3/services/61d3d05bdd1449f18923c83f52a4d762"
            },
            "name": "ec2",
            "type": "ec2"
        },
        {
            "description": "Glance Image Service",
            "enabled": true,
            "id": "69afa3d57d1948ea988beeb252bbaa5d",
            "links": {
                "self": "http://localhost:5000/v3/services/69afa3d57d1948ea988beeb252bbaa5d"
            },
            "name": "glance",
            "type": "image"
        },
        {
            "description": "Nova Compute Service V2.1",
            "enabled": true,
            "id": "79b691ee7be649d9bf8613efc0960206",
            "links": {
                "self": "http://localhost:5000/v3/services/79b691ee7be649d9bf8613efc0960206"
            },
            "name": "novav21",
            "type": "computev21"
        },
        {
            "description": "Swift Service",
            "enabled": true,
            "id": "92419b70ebe64c6c873bd20b14360e6b",
            "links": {
                "self": "http://localhost:5000/v3/services/92419b70ebe64c6c873bd20b14360e6b"
            },
            "name": "swift",
            "type": "object-store"
        },
        {
            "description": "Keystone Identity Service",
            "enabled": true,
            "id": "b8f8454fc07b46b781204d2a436f9d1c",
            "links": {
                "self": "http://localhost:5000/v3/services/b8f8454fc07b46b781204d2a436f9d1c"
            },
            "name": "keystone",
            "type": "identity"
        },
        {
            "description": "Cinder Volume Service",
            "enabled": true,
            "id": "cdda3bea0742407f95e70f4758f46558",
            "links": {
                "self": "http://localhost:5000/v3/services/cdda3bea0742407f95e70f4758f46558"
            },
            "name": "cinder",
            "type": "volume"
        }
    ]
}
POST
/v3/services
Create service

Creates a service.

 
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
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

service plain xsd:dict

A service object.

type plain xsd:string

The service type, which describes the API implemented by the service.

A valid value is compute, ec2, identity, image, network, or volume.

service_id (Optional) plain csapi:UUID

The service ID.

name (Optional) plain xsd:string

The service name.

description (Optional) plain xsd:string

The service description.

enabled (Optional) plain xsd:boolean

Defines whether the service and its endpoints appear in the service catalog:

  • false. The service and its endpoints do not appear in the service catalog.

  • true. The service and its endpoints appear in the service catalog.

Default is true.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the service resource.

service plain xsd:dict

A service object.

description plain xsd:string

The service description.

id plain csapi:UUID

The ID of the service.

name plain xsd:string

The service name.

type plain xsd:string

The service type, which describes the API implemented by the service. Value is compute, ec2, identity, image, network, or volume.

{
    "service": {
        "type": "compute",
        "name": "compute2",
        "description": "Compute service 2"
    }
}
{
    "service": {
        "name": "compute2",
        "links": {
            "self": "http://localhost:5000/v3/services/3f552eb79c48436db2868e948d8cf330"
        },
        "enabled": true,
        "type": "compute",
        "id": "3f552eb79c48436db2868e948d8cf330",
        "description": "Compute service 2"
    }
}
GET
/v3/services/​{service_id}​
Show service details

Shows details for a service.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

service_id URI csapi:UUID

The service ID.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the service resource.

service plain xsd:dict

A service object.

description plain xsd:string

The service description.

id plain csapi:UUID

The ID of the service.

name plain xsd:string

The service name.

type plain xsd:string

The service type, which describes the API implemented by the service. Value is compute, ec2, identity, image, network, or volume.

{
    "service": {
        "description": "Keystone Identity Service",
        "enabled": true,
        "id": "686766",
        "links": {
            "self": "http://identity:5000/v3/services/686766"
        },
        "name": "keystone",
        "type": "identity"
    }
}

This operation does not accept a request body.

PATCH
/v3/services/​{service_id}​
Update service

Updates a service.

 

The request body is the same as the create service request body, except that you include only those attributes that you want to update.

Normal response codes
200
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
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

service_id URI csapi:UUID

The service ID.

service plain xsd:dict

A service object.

type plain xsd:string

The service type, which describes the API implemented by the service.

A valid value is compute, ec2, identity, image, network, or volume.

name (Optional) plain xsd:string

The service name.

description (Optional) plain xsd:string

The service description.

enabled (Optional) plain xsd:boolean

Defines whether the service and its endpoints appear in the service catalog:

  • false. The service and its endpoints do not appear in the service catalog.

  • true. The service and its endpoints appear in the service catalog.

Default is true.

Response parameters
Parameter Style Type Description
links plain xsd:dict

The links for the service resource.

service plain xsd:dict

A service object.

description plain xsd:string

The service description.

id plain csapi:UUID

The ID of the service.

name plain xsd:string

The service name.

type plain xsd:string

The service type, which describes the API implemented by the service. Value is compute, ec2, identity, image, network, or volume.

{
    "service": {
        "description": "Block Storage Service V2"
    }
}
{
    "service": {
        "name": "cinderv2",
        "links": {
            "self": "http://localhost:5000/v3/services/5789da9864004dd088fce14c1c626a4b"
        },
        "enabled": true,
        "type": "volumev2",
        "id": "5789da9864004dd088fce14c1c626a4b",
        "description": "Block Storage Service V2"
    }
}
DELETE
/v3/services/​{service_id}​
Delete service

Deletes a service.

 

If you try to delete a service that still has associated endpoints, this call either deletes all associated endpoints or fails until all endpoints are deleted.

Normal response codes
204
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
X-Auth-Token header xsd:string

A valid authentication token for an administrative user.

service_id URI csapi:UUID

The service ID.

This operation does not accept a request body and does not return a response body.

GET
/v3/endpoints
List endpoints

Lists all available endpoints.

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

Filters the response by an interface.

service_id (Optional) query csapi:UUID

Filters the response by a service ID.

Response parameters
Parameter Style Type Description
endpoints plain xsd:list

An endpoints object.

enabled plain xsd:boolean

Indicates whether the endpoint appears in the service catalog:

  • false. The endpoint does not appear in the service catalog.

  • true. The endpoint appears in the service catalog.

id plain csapi:UUID

The endpoint UUID.

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.

links plain xsd:dict

The links for the endpoint resource.

region plain xsd:string

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

region_id plain csapi:UUID

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

service_id plain csapi:UUID

The UUID of the service to which the endpoint belongs.

url plain xsd:string

The endpoint URL.

links plain xsd:dict

The links for the endpoints resource.

{
    "endpoints": [
        {
            "enabled": true,
            "id": "0649c5be323f4792afbc1efdd480847d",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/0649c5be323f4792afbc1efdd480847d"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "ef6b15e425814dc69d830361baae0e33",
            "url": "http://23.253.211.234:8080/v1/AUTH_$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "06b85ed2aa57413ca0b1813daed329a9",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/06b85ed2aa57413ca0b1813daed329a9"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "98cfd5347fb84601b2f88f3afd8dddd4",
            "url": "http://23.253.211.234:8776/v1/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "070102f162e04f91a52c7887d0604163",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/070102f162e04f91a52c7887d0604163"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "312f401c14d143d8b3e3f4daf0418add",
            "url": "http://23.253.211.234:8774/v2.1/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "0fd73b621e424cc0a172853264519cbc",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/0fd73b621e424cc0a172853264519cbc"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "17a877162c8e405b81d563d95ec4e3f8",
            "url": "http://23.253.211.234:8776/v2/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "1899667a3b1544ccb355fdfc4184d7d7",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/1899667a3b1544ccb355fdfc4184d7d7"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "9b67aed49e0d4c2fb46ca9476a3b9243",
            "url": "http://23.253.211.234:9292"
        },
        {
            "enabled": true,
            "id": "3b3611ea2e554ee7b85e7f2213b02c33",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/3b3611ea2e554ee7b85e7f2213b02c33"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "2a662f90700b4478929d4b24cc6a320b",
            "url": "http://23.253.211.234:9696/"
        },
        {
            "enabled": true,
            "id": "3ea2b420306f48c6bf0cf51c2fefea03",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/3ea2b420306f48c6bf0cf51c2fefea03"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "736fb9bb21ef498287db9abcc55b20d9",
            "url": "http://23.253.211.234:8774/v2/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "41b122182f574a44b0e246aff6ca29c5",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/41b122182f574a44b0e246aff6ca29c5"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "9b67aed49e0d4c2fb46ca9476a3b9243",
            "url": "http://23.253.211.234:9292"
        },
        {
            "enabled": true,
            "id": "44a736dd5eeb4347acec66b5f11c8f80",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/44a736dd5eeb4347acec66b5f11c8f80"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "2a662f90700b4478929d4b24cc6a320b",
            "url": "http://23.253.211.234:9696/"
        },
        {
            "enabled": true,
            "id": "499e8f6718ef466ba3fb315fa8f9e0b8",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/499e8f6718ef466ba3fb315fa8f9e0b8"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "312f401c14d143d8b3e3f4daf0418add",
            "url": "http://23.253.211.234:8774/v2.1/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "545b1e9f126248428c5cdbec7420c353",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/545b1e9f126248428c5cdbec7420c353"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "736fb9bb21ef498287db9abcc55b20d9",
            "url": "http://23.253.211.234:8774/v2/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "629dc5a64e954ad09a45e87bc48299ba",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/629dc5a64e954ad09a45e87bc48299ba"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "2a662f90700b4478929d4b24cc6a320b",
            "url": "http://23.253.211.234:9696/"
        },
        {
            "enabled": true,
            "id": "642a329a660544fdaab2420c0da7d49b",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/642a329a660544fdaab2420c0da7d49b"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "ef6b15e425814dc69d830361baae0e33",
            "url": "http://23.253.211.234:8080/v1/AUTH_$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "72f8fc8536e44a19bc3388218efcc741",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/72f8fc8536e44a19bc3388218efcc741"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "9b67aed49e0d4c2fb46ca9476a3b9243",
            "url": "http://23.253.211.234:9292"
        },
        {
            "enabled": true,
            "id": "74121e71962e4947ac622c41706f0ee7",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/74121e71962e4947ac622c41706f0ee7"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "17a877162c8e405b81d563d95ec4e3f8",
            "url": "http://23.253.211.234:8776/v2/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "7431a4f971dc4abb8d0e387434a06817",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/7431a4f971dc4abb8d0e387434a06817"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "9242e05f0c23467bbd1cf1f7a6e5e596",
            "url": "http://23.253.211.234:8773/"
        },
        {
            "enabled": true,
            "id": "7cffc75a14ca4334b458e475750bd84f",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/7cffc75a14ca4334b458e475750bd84f"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "efeb249cbcd3412496bc4b194ea058da",
            "url": "http://23.253.211.234:5000/v2.0"
        },
        {
            "enabled": true,
            "id": "a422a6fa163b4a6ba8309e067ce3750b",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/a422a6fa163b4a6ba8309e067ce3750b"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "312f401c14d143d8b3e3f4daf0418add",
            "url": "http://23.253.211.234:8774/v2.1/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "ac6a74efe9944afdb129d4df70cde0ec",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/ac6a74efe9944afdb129d4df70cde0ec"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "9242e05f0c23467bbd1cf1f7a6e5e596",
            "url": "http://23.253.211.234:8773/"
        },
        {
            "enabled": true,
            "id": "adf43d7ff0d14d0fa1e8a5187f40e1af",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/adf43d7ff0d14d0fa1e8a5187f40e1af"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "efeb249cbcd3412496bc4b194ea058da",
            "url": "http://23.253.211.234:5000/v2.0"
        },
        {
            "enabled": true,
            "id": "b18be64a118244d39217db72534f8b33",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/b18be64a118244d39217db72534f8b33"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "736fb9bb21ef498287db9abcc55b20d9",
            "url": "http://23.253.211.234:8774/v2/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "c828983c9c214d819674649aa693cdff",
            "interface": "public",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/c828983c9c214d819674649aa693cdff"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "98cfd5347fb84601b2f88f3afd8dddd4",
            "url": "http://23.253.211.234:8776/v1/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "d062ebdb244f447498768fc0ced32e2d",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/d062ebdb244f447498768fc0ced32e2d"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "98cfd5347fb84601b2f88f3afd8dddd4",
            "url": "http://23.253.211.234:8776/v1/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "d281219ec0df4cf2b7c681463d5dcf51",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/d281219ec0df4cf2b7c681463d5dcf51"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "17a877162c8e405b81d563d95ec4e3f8",
            "url": "http://23.253.211.234:8776/v2/$(tenant_id)s"
        },
        {
            "enabled": true,
            "id": "d8e0824a17404431b5d978a87ac1bede",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/d8e0824a17404431b5d978a87ac1bede"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "efeb249cbcd3412496bc4b194ea058da",
            "url": "http://23.253.211.234:35357/v2.0"
        },
        {
            "enabled": true,
            "id": "d9b54bdc063046828ac3c6487bea8047",
            "interface": "internal",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/d9b54bdc063046828ac3c6487bea8047"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "9242e05f0c23467bbd1cf1f7a6e5e596",
            "url": "http://23.253.211.234:8773/"
        },
        {
            "enabled": true,
            "id": "ea74f9771dec475eabfc2cdff5364413",
            "interface": "admin",
            "links": {
                "self": "http://localhost:5000/v3/endpoints/ea74f9771dec475eabfc2cdff5364413"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "ef6b15e425814dc69d830361baae0e33",
            "url": "http://23.253.211.234:8080"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://localhost:5000/v3/endpoints"
    }
}
POST
/v3/endpoints
Create endpoint

Creates an endpoint.

 
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
endpoint plain xsd:dict

An endpoint object.

interface plain xsd:string

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

A valid 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.

name plain xsd:string

The endpoint name.

region_id (Optional) plain csapi:UUID

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

url plain xsd:string

The endpoint URL.

service_id plain csapi:UUID

The UUID of the service to which the endpoint belongs.

enabled (Optional) plain xsd:boolean

Defines whether the endpoint appears in the service catalog:

  • false. The endpoint does not appear in the service catalog.

  • true. The endpoint appears in the service catalog.

Default is true.

Response parameters
Parameter Style Type Description
endpoint plain xsd:dict

An endpoint object.

region_id plain csapi:UUID

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

links plain xsd:dict

The links for the endpoint resource.

url plain xsd:string

The endpoint URL.

region plain xsd:string

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

enabled plain xsd:boolean

Indicates whether the endpoint appears in the service catalog:

  • false. The endpoint does not appear in the service catalog.

  • true. The endpoint appears in the service catalog.

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.