Identity API v3 (CURRENT)

updated: 'Fri Jun 16 10:33:24 2017, commit 45265c0'

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

What’s New in Version 3.8¶

Allow a service user to fetch a token that has expired.
Add a password_expires_at query parameter to user list and users in group list.

What’s New in Version 3.7¶

Addition of the password_expires_at field to the user response object.
Introduce a flag to bypass expiration and revocation checking.

What’s New in Version 3.6¶

Listing role assignments for a tree of projects.
Setting the project is_domain attribute enables a project to behave as a domain.
Addition of the is_domain field to project scoped token response that represents whether a project is acting as a domain.
Enable or disable a subtree in the project hierarchy.
Delete a subtree in the project hierarchy.
Additional identifier for tokens scoped to the designated admin project.
Addition of domain_id filter to list user projects
One role can imply another via role_inference rules.
Enhance list role assignment to optionally provide names of entities.
The defaults for domain-specific configuration options can be retrieved.
Assignments can be specified as inherited, causing the assignment to be placed on any sub-projects.
Support for domain specific roles.
Support enabled and id as optional attributes to filter identity providers when listing.

What’s New in Version 3.5¶

Addition of type optional attribute to list credentials.
Addition of region_id optional attribute to list endpoints.
Addition of is_domain optional attribute to projects. Setting this currently has no effect, it is reserved for future use.

What’s New in Version 3.4¶

For tokenless authorization, the scope information may be set in the request headers.
Addition of parent_id optional attribute to projects. This enables the construction of a hierarchy of projects.
Addition of domain specific configuration management for a domain entity.
Removal of url optional attribute for regions. This attribute was only used for the experimental phase of keystone-to-keystone federation and has been superseded by making service provider entries have its own entry in the service catalog.
The JSON Home support now will indicate the status of resource if it is not stable and current.

What’s New in Version 3.3¶

These features are considered stable as of September 4th, 2014.

Addition of name optional variable to be included from service definition into the service catalog.
Introduced a stand alone call to retrieve a service catalog.
Introduced support for JSON Home.
Introduced a standard call to retrieve possible project and domain scope targets for a token.
Addition of url optional attribute for regions.

What’s New in Version 3.2¶

These features are considered stable as of January 23, 2014.

Introduced a mechanism to opt-out from catalog information during token validation
Introduced a region resource for constructing a hierarchical container of groups of service endpoints
Inexact filtering is supported on string attributes
Listing collections may indicate only a subset of the data has been provided if a particular deployment has limited the number of entries a query may return

What’s New in Version 3.1¶

These features are considered stable as of July 18, 2013.

A token without an explicit scope of authorization is issued if the user does not specify a project and does not have authorization on the project specified by their default project attribute
Introduced a generalized call for getting role assignments, with filtering for user, group, project, domain and role
Introduced a mechanism to opt-out from catalog information during token creation
Added optional bind information to token structure

What’s New in Version 3.0¶

These features are considered stable as of February 20, 2013.

Former “Service” and “Admin” APIs (including CRUD operations previously defined in the v2 OS-KSADM extension) are consolidated into a single core API
“Tenants” are now known as “projects”
“Groups”: a container representing a collection of users
“Domains”: a high-level container for projects, users and groups
“Policies”: a centralized repository for policy engine rule sets
“Credentials”: generic credential storage per user (e.g. EC2, PKI, SSH, etc.)
Roles can be granted at either the domain or project level
User, group and project names only have to be unique within their owning domain
Retrieving your list of projects (previously GET /tenants) is now explicitly based on your user ID: GET /users/{user_id}/projects
Tokens explicitly represent user+project or user+domain pairs
Partial updates are performed using the HTTP PATCH method
Token ID values no longer appear in URLs

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

Authentication and token management¶

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.

In v3.7 of the Identity API service, two new configuration options were added: [resource] admin_project_name and [resource] admin_project_domain_name. The options represent the project that only the cloud administrator should be able to access. When an authentication request for a token scoped to the admin project is processed, it will have an additional field in the token {is_admin_project: True}. The additional field can be used when writing policy rules that evaluate access control to APIs.

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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
domain	body	object	A `domain` object, containing:
name (Optional)	body	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.
auth	body	object	An `auth` object.
user	body	object	A `user` object.
password	body	object	The `password` object, contains the authentication information.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
identity	body	object	An `identity` object.
methods	body	array	The authentication method. For password authentication, specify `password`.

Request Example¶

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "name": "admin",
                    "domain": {
                        "name": "Default"
                    },
                    "password": "devstacker"
                }
            }
        }
    }
}

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain	body	object	A `domain` object, containing:
methods	body	array	The authentication method. For password authentication, specify `password`.
expires_at	body	string	The date and time when the token expires. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`. A `null` value indicates that the token never expires.
token	body	object	A `token` object.
extras	body	object	A set of metadata key and value pairs, if any.
user	body	object	A `user` object.
audit_ids	body	array	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	body	string	The date and time when the token was issued. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
name (Optional)	body	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.

Response Example¶

{
    "token": {
        "methods": [
            "password"
        ],
        "expires_at": "2015-11-06T15:32:17.893769Z",
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "423f19a4ac1e4f48bbb4180756e6eb6c",
            "name": "admin",
            "password_expires_at": null
        },
        "audit_ids": [
            "ZzZwkUflQfygX7pdYDBCQQ"
        ],
        "issued_at": "2015-11-06T14:32:17.893797Z"
    }
}

POST

/v3/auth/tokens

Password authentication with scoped authorization

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
name (Optional)	body	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.
auth	body	object	An `auth` object.
user	body	object	A `user` object.
scope (Optional)	body	string	The authorization scope, including either a project or a domain (Since v3.4). If both a domain and a project are specified, an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to both a project and a domain. An ID is sufficient to uniquely identify a project but if a project is specified by name, then the domain of the project must also be specified in order to uniquely identify the project by name. A domain scope may be specified by either the domain’s ID or name with equivalent results.
password	body	object	The `password` object, contains the authentication information.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
identity	body	object	An `identity` object.
methods	body	array	The authentication method. For password authentication, specify `password`.

Request Example¶

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "project": {
                "id": "a6944d763bf64ee6a275f1263fae0352"
            }
        }
    }
}

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain	body	object	A `domain` object, containing:
region_id	body	string	(Since v3.2) The ID of the region that contains the service endpoint.
methods	body	array	The authentication method. For password authentication, specify `password`.
roles	body	array	A list of `role` objects, each containing:
url	body	string	The endpoint URL.
region	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
token	body	object	A `token` object.
expires_at	body	string	The date and time when the token expires. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`. A `null` value indicates that the token never expires.
project	body	object	A `project` object, containing:
issued_at	body	string	The date and time when the token was issued. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`.
catalog	body	array	A `catalog` object.
extras	body	object	A set of metadata key and value pairs, if any.
user	body	object	A `user` object.
audit_ids	body	array	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.
interface	body	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.
endpoints	body	array	A list of `endpoint` objects.
type	body	string	The endpoint type.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
name (Optional)	body	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.

POST

/v3/auth/tokens

Password authentication with explicit unscoped authorization

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
name (Optional)	body	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.
auth	body	object	An `auth` object.
user	body	object	A `user` object.
scope (Optional)	body	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 an explicit, `unscoped` token request is not made and the role has a default project, then the response will 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.
password	body	object	The `password` object, contains the authentication information.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
identity	body	object	An `identity` object.
methods	body	array	The authentication method. For password authentication, specify `password`.

Request Example¶

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": "unscoped"
    }
}

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain	body	object	A `domain` object, containing:
methods	body	array	The authentication method. For password authentication, specify `password`.
roles	body	array	A list of `role` objects, each containing:
expires_at	body	string	The date and time when the token expires. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`. A `null` value indicates that the token never expires.
token	body	object	A `token` object.
extras	body	object	A set of metadata key and value pairs, if any.
user	body	object	A `user` object.
audit_ids	body	array	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	body	string	The date and time when the token was issued. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
name (Optional)	body	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.

POST

/v3/auth/tokens

Token authentication with unscoped authorization

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
identity	body	object	An `identity` object.
token	body	object	A `token` object. The token authentication method is used. This method is typically used in combination with a request to change authorization scope.
id	body	string	A token ID.
auth	body	object	An `auth` object.
methods	body	array	The authentication method. For token authentication, specify `token`.

Request Example¶

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        }
    }
}

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.

POST

/v3/auth/tokens

Token authentication with scoped authorization

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
methods	body	array	The authentication method. For token authentication, specify `token`.
auth	body	object	An `auth` object.
token	body	object	A `token` object. The token authentication method is used. This method is typically used in combination with a request to change authorization scope.
audit_ids	body	array	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.
scope (Optional)	body	string	The authorization scope, including either a project or a domain (Since v3.4). If both a domain and a project are specified, an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to both a project and a domain. An ID is sufficient to uniquely identify a project but if a project is specified by name, then the domain of the project must also be specified in order to uniquely identify the project by name. A domain scope may be specified by either the domain’s ID or name with equivalent results.
id	body	string	A token ID.
identity	body	object	An `identity` object.

Request Example¶

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "project": {
                "id": "5b50efd009b540559104ee3c03bbb2b7"
            }
        }
    }
}

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.

POST

/v3/auth/tokens

Token authentication with explicit unscoped authorization

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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

In the request body, provide the token ID and the unscoped authorization scope.

Normal response codes: 201

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
methods	body	array	The authentication method. For token authentication, specify `token`.
auth	body	object	An `auth` object.
token	body	object	A `token` object. The token authentication method is used. This method is typically used in combination with a request to change authorization scope.
audit_ids	body	array	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.
scope (Optional)	body	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 an explicit, `unscoped` token request is not made and the role has a default project, then the response will 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.
id	body	string	A token ID.
identity	body	object	An `identity` object.

Request Example¶

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": "unscoped"
    }
}

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.

GET

/v3/auth/tokens

Validate and show information for token

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
X-Auth-Token	header	string	A valid authentication token for an administrative user.
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
nocatalog (Optional)	query	string	(Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.
allow_expired (Optional)	query	bool	(Since v3.8) Allow fetching a token that has expired. By default expired tokens return a 404 exception.

Response Parameters¶

Name	In	Type	Description
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain	body	object	A `domain` object, containing:
methods	body	array	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.
links	body	object	The links to the `domain` resource.
user	body	object	A `user` object.
token	body	object	A `token` object.
expires_at	body	string	The date and time when the token expires. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`. A `null` value indicates that the token never expires.
project	body	object	A `project` object, containing:
catalog	body	array	A `catalog` object.
extras	body	object	A set of metadata key and value pairs, if any.
roles	body	array	A list of `role` objects, each containing:
audit_ids	body	array	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	body	string	The date and time when the token was issued. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss.sssZ For example, `2015-08-27T09:49:58.000000Z`.
id (Optional)	body	string	The ID of the user. Required if you do not specify the user name.
name (Optional)	body	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.

Response Example¶

{
    "token": {
        "methods": [
            "token"
        ],
        "expires_at": "2015-11-05T22:00:11.000000Z",
        "extras": {},
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "10a2e6e717a245d9acad3e5f97aeca3d",
            "name": "admin",
            "password_expires_at": null
        },
        "audit_ids": [
            "mAjXQhiYRyKwkB4qygdLVg"
        ],
        "issued_at": "2015-11-05T21:00:33.819948Z"
    }
}

HEAD

/v3/auth/tokens

Check token

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
X-Auth-Token	header	string	A valid authentication token for an administrative user.
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
allow_expired (Optional)	query	bool	(Since v3.8) Allow fetching a token that has expired. By default expired tokens return a 404 exception.

DELETE

/v3/auth/tokens

Revoke token

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

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.

Normal response codes: 204

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
X-Auth-Token	header	string	A valid authentication token for an administrative user.
X-Subject-Token	header	string	The authentication token. An authentication response returns the token ID in this header rather than in the response body.

GET

/v3/auth/catalog

Get service catalog

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_catalog

New in version 3.3

This call returns a service catalog for the X-Auth-Token provided in the request, even if the token does not contain a catalog itself (for example, if it was generated using ?nocatalog).

The structure of the catalog object is identical to that contained in a token.

Normal response codes: 200

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
X-Auth-Token	header	string	A valid authentication token for an administrative user.

Response Parameters¶

Name	In	Type	Description
endpoints	body	array	A list of `endpoint` objects.
id	body	string	The UUID of the service to which the endpoint belongs.
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
name	body	string	The service name.

Response Example¶

{
    "catalog": [
        {
            "endpoints": [
                {
                    "id": "39dc322ce86c4111b4f06c2eeae0841b",
                    "interface": "public",
                    "region": "RegionOne",
                    "url": "http://localhost:5000"
                },
                {
                    "id": "ec642f27474842e78bf059f6c48f4e99",
                    "interface": "internal",
                    "region": "RegionOne",
                    "url": "http://localhost:5000"
                },
                {
                    "id": "c609fc430175452290b62a4242e8a7e8",
                    "interface": "admin",
                    "region": "RegionOne",
                    "url": "http://localhost:35357"
                }
            ],
            "id": "4363ae44bdf34a3981fde3b823cb9aa2",
            "type": "identity",
            "name": "keystone"
        }
    ],
    "links": {
        "self": "https://example.com/identity/v3/catalog",
        "previous": null,
        "next": null
    }
}

GET

/v3/auth/projects

Get available project scopes

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_projects

New in version 3.3

This call returns the list of projects that are available to be scoped to based on the X-Auth-Token provided in the request.

The structure of the response is exactly the same as listing projects for a user.

Normal response codes: 204

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
X-Auth-Token	header	string	A valid authentication token for an administrative user.

Response Parameters¶

Name	In	Type	Description
domain_id	body	string	The ID of the domain for the project.
enabled	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled.
id	body	string	The ID for the project.
links	body	object	The links for the `project` resource.
name	body	string	The name of the project.

Response Example¶

{
    "projects": [
        {
            "domain_id": "1789d1",
            "enabled": true,
            "id": "263fd9",
            "links": {
                "self": "https://example.com/identity/v3/projects/263fd9"
            },
            "name": "Test Group"
        },
        {
            "domain_id": "1789d1",
            "enabled": true,
            "id": "50ef01",
            "links": {
                "self": "https://example.com/identity/v3/projects/50ef01"
            },
            "name": "Build Group"
        }
    ],
    "links": {
        "self": "https://example.com/identity/v3/auth/projects",
        "previous": null,
        "next": null
    }
}

GET

/v3/auth/domains

Get available domain scopes

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_domains

New in version 3.3

This call returns the list of domains that are available to be scoped to based on the X-Auth-Token provided in the request.

The structure is the same as listing domains.

Normal response codes: 204

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
X-Auth-Token	header	string	A valid authentication token for an administrative user.

Response Parameters¶

Name	In	Type	Description
description	body	string	The description of the domain.
enabled	body	string	If set to `true`, domain is enabled. If set to `false`, domain is disabled.
id	body	string	The ID of the domain.
links	body	object	The links to the `domain` resource.
name	body	string	The name of the domain.

Response Example¶

{
    "domains": [
        {
            "description": "my domain description",
            "enabled": true,
            "id": "1789d1",
            "links": {
                "self": "https://example.com/identity/v3/domains/1789d1"
            },
            "name": "my domain"
        },
        {
            "description": "description of my other domain",
            "enabled": true,
            "id": "43e8da",
            "links": {
                "self": "https://example.com/identity/v3/domains/43e8da"
            },
            "name": "another domain"
        }
    ],
    "links": {
        "self": "https://example.com/identity/v3/auth/domains",
        "previous": null,
        "next": null
    }
}

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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/credentials

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
credential	body	object	A `credential` object.
project_id	body	string	The ID for the project.
type	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.
blob	body	string	The credential itself, as a serialized blob.
user_id	body	string	The ID of the user who owns the credential.

Request Example¶

{
    "credential": {
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "user_id": "bb5476fd12884539b41d5a88f838d773"
    }
}

Response Parameters¶

Name	In	Type	Description
credential	body	object	A `credential` object.
user_id	body	string	The ID of the user who owns the credential.
links	body	object	The links for the `credential` resource.
blob	body	string	The credential itself, as a serialized blob.
project_id	body	string	The ID for the project.
type	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.
id	body	string	The UUID for the credential.

Response Example¶

{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773",
        "links": {
            "self": "http://example.com/identity/v3/credentials/3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510"
        },
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "id": "3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510"
    }
}

GET

/v3/credentials

List credentials

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/credentials

Lists all credentials.

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

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
user_id (Optional)	query	string	Filters the response by a user ID.
type (Optional)	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.

Response Parameters¶

Name	In	Type	Description
user_id	body	string	The ID of the user who owns the credential.
links	body	object	The links for the `credentials` resource.
blob	body	string	The credential itself, as a serialized blob.
credentials	body	array	A list of `credential` objects.
project_id	body	string	The ID for the project.
type	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.
id	body	string	The UUID for the credential.

Response Example¶

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

GET

/v3/credentials/{credential_id}

Show credential details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/credential

Shows details for a credential.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
credential_id	path	string	The UUID for the credential.

Response Parameters¶

Name	In	Type	Description
credential	body	object	A `credential` object.
user_id	body	string	The ID of the user who owns the credential.
links	body	object	The links for the `credential` resource.
blob	body	string	The credential itself, as a serialized blob.
project_id	body	string	The ID for the project.
type	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.
id	body	string	The UUID for the credential.

Response Example¶

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

PATCH

/v3/credentials/{credential_id}

Update credential

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/credential

Updates a credential.

Normal response codes: 200

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
credential_id	path	string	The UUID for the credential.
credential	body	object	A `credential` object.
project_id	body	string	The ID for the project.
type (Optional)	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.
blob (Optional)	body	string	The credential itself, as a serialized blob.
user_id (Optional)	body	string	The ID of the user who owns the credential.

Request Example¶

{
    "credential": {
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "user_id": "bb5476fd12884539b41d5a88f838d773"
    }
}

Response Parameters¶

Name	In	Type	Description
credential	body	object	A `credential` object.
user_id	body	string	The ID of the user who owns the credential.
links	body	object	The links for the `credential` resource.
blob	body	string	The credential itself, as a serialized blob.
project_id	body	string	The ID for the project.
type	body	string	The credential type, such as `ec2` or `cert`. The implementation determines the list of supported types.
id	body	string	The UUID for the credential.

Response Example¶

{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773",
        "links": {
            "self": "http://example.com/identity/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
        },
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}",
        "project_id": "731fc6f265cd486d900f16e84c5cb594",
        "type": "ec2",
        "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7"
    }
}

DELETE

/v3/credentials/{credential_id}

Delete credential

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/credential

Deletes a credential.

Normal response codes: 204

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
credential_id	path	string	The UUID for the credential.

Domains¶

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. Unique within the owning domain.
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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domains

Lists all domains.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
name (Optional)	query	string	Filters the response by a domain name.
enabled (Optional)	query	string	If set to true, then only domains that are enabled will be returned, if set to false only that are disabled will be returned. Any value other than `0`, including no value, will be interpreted as true.

Response Parameters¶

Name	In	Type	Description
domains	body	array	A list of `domain` objects, each containing:
description	body	string	The description of the domain.
enabled	body	string	If set to `true`, domain is enabled. If set to `false`, domain is disabled.
id	body	string	The ID of the domain.
links	body	object	The links to the `domain` resource.
name	body	string	The name of the domain.

Response Example¶

{
    "domains": [
        {
            "description": "Used for swift functional testing",
            "enabled": true,
            "id": "5a75994a383c449184053ff7270c4e91",
            "links": {
                "self": "http://example.com/identity/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://example.com/identity/v3/domains/default"
            },
            "name": "Default"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/domains"
    }
}

POST

/v3/domains

Create domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domains

Creates a domain.

Normal response codes: 201

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
domain	body	object	A `domain` object, containing:
enabled (Optional)	body	string	If set to `true`, domain is created enabled. If set to `false`, domain is created disabled. The default is `true`. Users can only authorize against an enabled domain (and any of its projects). In addition, users can only authenticate if the domain that owns them is also enabled. Disabling a domain prevents both of these things.
description (Optional)	body	string	The description of the domain.
name	body	string	The name of the domain.

Request Example¶

{
    "domain": {
        "description": "Domain description",
        "enabled": true,
        "name": "myDomain"
    }
}

Response Parameters¶

Name	In	Type	Description
domain	body	object	A `domain` object, containing:
description	body	string	The description of the domain.
enabled	body	string	If set to `true`, domain is enabled. If set to `false`, domain is disabled.
id	body	string	The ID of the domain.
links	body	object	The links to the `domain` resource.
name	body	string	The name of the domain.

GET

/v3/domains/{domain_id}

Show domain details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domains

Shows details for a domain.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.

Response Parameters¶

Name	In	Type	Description
domain	body	object	A `domain` object, containing:
description	body	string	The description of the domain.
enabled	body	string	If set to `true`, domain is enabled. If set to `false`, domain is disabled.
id	body	string	The ID of the domain.
links	body	object	The links to the `domain` resource.
name	body	string	The name of the domain.

Response Example¶

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

PATCH

/v3/domains/{domain_id}

Update domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain

Updates a domain.

Normal response codes: 200

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
domain	body	object	A `domain` object, containing:
enabled (Optional)	body	string	If set to `true`, domain is enabled. If set to `false`, domain is disabled. The default is `true`. Users can only authorize against an enabled domain (and any of its projects). In addition, users can only authenticate if the domain that owns them is also enabled. Disabling a domain prevents both of these things. When you disable a domain, all tokens that are authorized for that domain become no longer valid. If you reenable the domain, these tokens are not re-enabled.
description (Optional)	body	string	The new description of the domain.
name (Optional)	body	string	The new name of the domain.

Request Example¶

{
    "domain": {
        "description": "Owns users and projects on Identity API v2."
    }
}

Response Parameters¶

Name	In	Type	Description
domain	body	object	A `domain` object, containing:
description	body	string	The description of the domain.
enabled	body	string	If set to `true`, domain is enabled. If set to `false`, domain is disabled.
id	body	string	The ID of the domain.
links	body	object	The links to the `domain` resource.
name	body	string	The name of the domain.

Response Example¶

{
    "domain": {
        "links": {
            "self": "http://example.com/identity/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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/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.

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

Normal response codes: 204

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.

Domain configuration¶

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/config/default

Show default configuration settings

The default configuration settings for the options that can be overridden can be retrieved.

Relationship:: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

Response Parameters¶

Name	In	Type	Description
config	body	object	A `config` object.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
url	body	string	The LDAP URL.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.
driver	body	string	The Identity backend driver.

Response Example¶

{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "ldap://localhost",
            "user": "",
            "suffix": "cn=example,cn=com",
            ....
        }
    }
}

GET

/v3/domains/config/{group}/default

Show default configuration for a group

Reads the default configuration settings for a specific group.

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

The API supports only the identity and ldap groups.

Normal response codes: 200

Error response codes: 413, 405, 404, 403, 401, 400, 503

Request¶

Name	In	Type	Description
group	path	string	The group ID.

Response Parameters¶

Name	In	Type	Description
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
url	body	string	The LDAP URL.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.
driver	body	string	The Identity backend driver.

Response Example¶

{
    "ldap": {
        "url": "ldap://localhost",
        "user": "",
        "suffix": "cn=example,cn=com".
        ....
    }
}

GET

/v3/domains/config/{group}/{option}/default

Show default option for a group

Reads the default configuration setting for an option within a group.

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

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: 413, 405, 404, 403, 401, 400, 503

Request¶

Name	In	Type	Description
group	path	string	The group ID.
option	path	string	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¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.

Response Example¶

{
    "driver": "ldap"
}

GET

/v3/domains/{domain_id}/config/{group}/{option}

Show domain group option configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

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: 413, 405, 404, 403, 401, 400, 503

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group	path	string	The group ID.
option	path	string	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¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

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

PATCH

/v3/domains/{domain_id}/config/{group}/{option}

Update domain group option configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

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: 413, 415, 405, 404, 403, 401, 400, 503, 409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group	path	string	The group ID.
option	path	string	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`.
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Request Example¶

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

Response Parameters¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

{
    "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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

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: 413, 415, 405, 404, 403, 401, 400, 503, 409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group	path	string	The group ID.
option	path	string	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`.

GET

/v3/domains/{domain_id}/config/{group}

Show domain group configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

Shows details for a domain group configuration.

The API supports only the identity and ldap groups.

Normal response codes: 200

Error response codes: 413, 405, 404, 403, 401, 400, 503

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group	path	string	The group ID.

Response Parameters¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

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

PATCH

/v3/domains/{domain_id}/config/{group}

Update domain group configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

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: 413, 415, 405, 404, 403, 401, 400, 503, 409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group	path	string	The group ID.
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Request Example¶

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

Response Parameters¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

{
    "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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default

Deletes a domain group configuration.

The API supports only the identity and ldap groups.

Normal response codes: 204

Error response codes: 413, 415, 405, 404, 403, 401, 400, 503, 409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group	path	string	The group ID.

PUT

/v3/domains/{domain_id}/config

Create domain configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config

Creates a domain configuration.

Normal response codes: 200, 201

Error response codes: 413, 405, 404, 403, 401, 400, 503

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Request Example¶

{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "ldap://myldap.com:389/",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}

Response Parameters¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "ldap://myldap.com:389/",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}

GET

/v3/domains/{domain_id}/config

Show domain configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config

Shows details for a domain configuration.

Normal response codes: 200

Error response codes: 413, 405, 404, 403, 401, 400, 503

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.

Response Parameters¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

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

PATCH

/v3/domains/{domain_id}/config

Update domain configuration

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config

Updates a domain configuration.

Normal response codes: 200

Error response codes: 413, 415, 405, 404, 403, 401, 400, 503, 409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Request Example¶

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

Response Parameters¶

Name	In	Type	Description
url	body	string	The LDAP URL.
driver	body	string	The Identity backend driver.
ldap	body	object	An `ldap` object. Required to set the LDAP group configuration options.
config	body	object	A `config` object.
user_tree_dn	body	string	The base distinguished name (DN) of LDAP, from where all users can be reached. For example, `ou=Users,dc=root,dc=org`.
identity	body	object	An `identity` object.

Response Example¶

{
    "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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_config

Deletes a domain configuration.

Normal response codes: 204

Error response codes: 413, 415, 405, 404, 403, 401, 400, 503, 409

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.

Groups¶

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

You can use groups to ease the task of managing role assignments for users. Assigning a role to a group on a project or domain is equivalent to assigning the role to each group member on that project or domain.

When you unassign a role from a group, that role is automatically unassigned from any user that is a member of the group. Any tokens that authenticates those users to the relevant project or domain are revoked.

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

GET

/v3/groups

List groups

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/groups

Lists groups.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
name (Optional)	query	string	Filters the response by a group name.
domain_id (Optional)	query	string	Filters the response by a domain ID.

Response Parameters¶

Name	In	Type	Description
links	body	object	The link to the collection of resources.
groups	body	array	A list of `group` objects, each containing:
description	body	string	The description of the group.
domain_id	body	string	The ID of the domain of the group.
id	body	string	The ID of the group.
links	body	object	The link to the resources in question.
name	body	string	The name of the group.

Response Example¶

{
    "links": {
        "self": "http://example.com/identity/v3/groups",
        "previous": null,
        "next": null
    },
    "groups": [
        {
            "description": "non-admin group",
            "domain_id": "default",
            "id": "96372bbb152f475aa37e9a76a25a029c",
            "links": {
                "self": "http://example.com/identity/v3/groups/96372bbb152f475aa37e9a76a25a029c"
            },
            "name": "nonadmins"
        },
        {
            "description": "openstack admin group",
            "domain_id": "default",
            "id": "9ce0ad4e58a84d7a97b92f7955d10c92",
            "links": {
                "self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92"
            },
            "name": "admins"
        }
    ]
}

POST

/v3/groups

Create group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/groups

Creates a group.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
group	body	object	A `group` object, containing:
description	body	string	The description of the group.
domain_id	body	string	The ID of the domain of the group.
name	body	string	The name of the group.

Request Example¶

{
    "group": {
        "description": "Contract developers",
        "domain_id": "default",
        "name": "Contract developers"
    }
}

Response Parameters¶

Name	In	Type	Description
group	body	object	A `group` object, containing:
description	body	string	The description of the group.
domain_id	body	string	The ID of the domain of the group.
id	body	string	The ID of the group.
links	body	object	The link to the resources in question.
name	body	string	The name of the group.

Response Example¶

{
    "group": {
        "description": "Contract developers",
        "domain_id": "default",
        "id": "c0d675eac29945ad9dfd08aa1bb75751",
        "links": {
            "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"
        },
        "name": "Contract developers"
    }
}

GET

/v3/groups/{group_id}

Show group details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group

Shows details for a group.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
group_id	path	string	The group ID.

Response Parameters¶

Name	In	Type	Description
group	body	object	A `group` object, containing:
description	body	string	The description of the group.
domain_id	body	string	The ID of the domain of the group.
id	body	string	The ID of the group.
links	body	object	The link to the resources in question.
name	body	string	The name of the group.

Response Example¶

{
    "group": {
        "description": "Contract developers",
        "domain_id": "default",
        "id": "c0d675eac29945ad9dfd08aa1bb75751",
        "links": {
            "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"
        },
        "name": "Contract developers"
    }
}

PATCH

/v3/groups/{group_id}

Update group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group

Updates a group.

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

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.
`501 - Not Implemented`	The server either does not recognize the request method, or it lacks the ability to fulfill the request.

Request Parameters¶

Name	In	Type	Description
group_id	path	string	The group ID.
group	body	object	A `group` object, containing:
description (Optional)	body	string	The new description of the group.
domain_id (Optional)	body	string	The ID of the new domain for the group. The ability to change the domain of a group is now deprecated, and will be removed in subsequent release. It is already disabled by default in most Identity service implementations.
name (Optional)	body	string	The new name of the group.

Request Example¶

{
    "group": {
        "description": "Contract developers 2016",
        "name": "Contract developers 2016"
    }
}

Response Parameters¶

Name	In	Type	Description
group	body	object	A `group` object, containing:
description	body	string	The description of the group.
domain_id	body	string	The ID of the domain of the group.
id	body	string	The ID of the group.
links	body	object	The link to the resources in question.
name	body	string	The name of the group.

Response Example¶

{
    "group": {
        "description": "Contract developers 2016",
        "domain_id": "default",
        "id": "c0d675eac29945ad9dfd08aa1bb75751",
        "links": {
            "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"
        },
        "name": "Contract developers 2016"
    }
}

DELETE

/v3/groups/{group_id}

Delete group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group

Deletes a group.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
group_id	path	string	The group ID.

GET

/v3/groups/{group_id}/users

List users in group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group_users

Lists the users that belong to a group.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name In Type Description

group_id path string The group ID.

password_expires_at (Optional)

query

string

Filter results based on which user passwords have expired. The query should include an operator and a timestamp with a colon (:) separating the two, for example:

password_expires_at={operator}:{timestamp}

Valid operators are: lt, lte, gt, gte, eq, and neq
- lt: expiration time lower than the timestamp
- lte: expiration time lower than or equal to the timestamp
- gt: expiration time higher than the timestamp
- gte: expiration time higher than or equal to the timestamp
- eq: expiration time equal to the timestamp
- neq: expiration time not equal to the timestamp
Valid timestamps are of the form: YYYY-MM-DDTHH:mm:ssZ.

For example:

/v3/users?password_expires_at=lt:2016-12-08T22:02:00Z

The example would return a list of users whose password expired before the timestamp (2016-12-08T22:02:00Z).

Response Example¶

{
    "links": {
        "self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92/users",
        "previous": null,
        "next": null
    },
    "users": [
        {
            "domain_id": "default",
            "description": null,
            "enabled": true,
            "id": "acd565a08293c1e48bc0dd0d72ad5d5d"
            "name": "Henry",
            "links": {
                "self": "http://example.com/identity/v3/users/acd565a08293c1e48bc0dd0d72ad5d5d"
            }
        },
        {
            "domain_id": "default",
            "description": null,
            "enabled": true,
            "id": "fff603a0829d41e48bc0dd0d72ad61ce",
            "name": "Paul",
            "links": {
                "self": "http://example.com/identity/v3/users/fff603a0829d41e48bc0dd0d72ad61ce"
            },
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    ]
}

PUT

/v3/groups/{group_id}/users/{user_id}

Add user to group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group_user

Adds a user to a group.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.
group_id	path	string	The group ID.

HEAD

/v3/groups/{group_id}/users/{user_id}

Check whether user belongs to group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group_user

Validates that a user belongs to a group.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.
group_id	path	string	The group ID.

DELETE

/v3/groups/{group_id}/users/{user_id}

Remove user from group

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/group_user

Removes a user from a group.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.
group_id	path	string	The group ID.

OS-INHERIT API¶

Enables projects to inherit role assignments from either their owning domain or projects that are higher in the hierarchy.

(Since API v3.4) The OS-INHERIT extension allows inheritance from both projects and domains. To access project inheritance, the Identity service server must run at least API v3.4.

PUT

/v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects

Assign role to user on projects owned by domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_user_role_inherited_to_projects

Assigns a role to a user in projects owned by a domain.

The inherited role is only applied to the owned projects (both existing and future projects), and will not appear as a role in a domain scoped token.

Normal response codes: 204

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
role_id	path	string	The role ID.
user_id	path	string	The user ID.

PUT

/v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects

Assign role to group on projects owned by a domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_group_role_inherited_to_projects

The inherited role is only applied to the owned projects (both existing and future projects), and will not appear as a role in a domain scoped token.

Normal response codes: 204

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The role ID.
role_id	path	string	The user ID.

GET

/v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/inherited_to_projects

List user’s inherited project roles on a domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_user_roles_inherited_to_projects

The list only contains those role assignments to the domain that were specified as being inherited to projects within that domain.

Normal response codes: 200

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
user_id	path	string	The user ID.

Response Example¶

{
    "roles": [
        {
            "id": "91011",
            "links": {
                "self": "http://example.com/identity/v3/roles/91011"
            },
            "name": "admin"
        },
        {
            "id": "91011",
            "links": {
                "self": "http://example.com/identity/v3/roles/91011"
            },
            "name": "admin"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-INHERIT/domains/1234/users/5678/roles/inherited_to_projects",
        "previous": null,
        "next": null
    }
}

GET

/v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/inherited_to_projects

List group’s inherited project roles on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_group_roles_inherited_to_projects

The list only contains those role assignments to the domain that were specified as being inherited to projects within that domain.

Normal response codes: 200

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.

Response Example¶

{
    "roles": [
        {
            "id": "91011",
            "links": {
                "self": "http://example.com/identity/v3/roles/91011"
            },
            "name": "admin"
        },
        {
            "id": "91011",
            "links": {
                "self": "http://example.com/identity/v3/roles/91011"
            },
            "name": "admin"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-INHERIT/domains/1234/groups/5678/roles/inherited_to_projects",
        "previous": null,
        "next": null
    }
}

HEAD

/v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects

Check if user has an inherited project role on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_user_role_inherited_to_projects

Checks whether a user has an inherited project role in a domain.

Normal response codes: 204

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
role_id	path	string	The role ID.
user_id	path	string	The user ID.

HEAD

/v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects

Check if group has an inherited project role on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_group_role_inherited_to_projects

Checks whether a group has an inherited project role in a domain.

Normal response codes: 204

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

DELETE

/v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects

Revoke an inherited project role from user on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_user_role_inherited_to_projects

Revokes an inherited project role from a user in a domain.

Normal response codes: 204

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
role_id	path	string	The role ID.
user_id	path	string	The user ID.

DELETE

/v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects

Revoke an inherited project role from group on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/domain_group_role_inherited_to_projects

Revokes an inherited project role from a group in a domain.

Normal response codes: 204

Request¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

PUT

/v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects

Assign role to user on projects in a subtree

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/project_user_role_inherited_to_projects

The inherited role assignment is anchored to a project and applied to its subtree in the projects hierarchy (both existing and future projects).

Note: The inherited role is not applied to the project itself, and only applied to its subtree projects.
Note: It is possible for a user to have both a regular (non-inherited) and an inherited role assignment on the same project.
Note: The request doesn’t require a body, which will be ignored if provided.

Normal response codes: 204

Request¶

Name	In	Type	Description
project_id	body	string	The ID for the project.
role_id	path	string	The role ID.
user_id	path	string	The user ID.

PUT

/v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects

Assign role to group on projects in a subtree

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/project_group_role_inherited_to_projects

The inherited role assignment is anchored to a project and applied to its subtree in the projects hierarchy (both existing and future projects).

Note: The inherited role is not applied to the project itself, and only applied to its subtree projects.
Note: It is possible for a group to have both a regular (non-inherited) and an inherited role assignment on the same project.
Note: The request doesn’t require a body, which will be ignored if provided.

Normal response codes: 204

Request¶

Name	In	Type	Description
group_id	path	string	The group ID.
project_id	path	string	The project ID.
role_id	path	string	The role ID.

HEAD

/v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects

Check if user has an inherited project role on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/project_user_role_inherited_to_projects

Checks whether a user has a role assignment with the inherited_to_projects flag in a project.

Normal response codes: 200

Request¶

Name	In	Type	Description
project_id	path	string	The project ID.
role_id	path	string	The role ID.
user_id	path	string	The user ID.

HEAD

/v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects

Check if group has an inherited project role on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/project_group_role_inherited_to_projects

Checks whether a group has a role assignment with the inherited_to_projects flag in a project.

Normal response codes: 200

Request¶

Name	In	Type	Description
group_id	path	string	The group ID.
project_id	path	string	The project ID.
role_id	path	string	The role ID.

DELETE

/v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects

Revoke an inherited project role from user on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/project_user_role_inherited_to_projects

Normal response codes: 204

Request¶

Name	In	Type	Description
project_id	path	string	The project ID.
role_id	path	string	The role ID.
user_id	path	string	The user ID.

DELETE

/v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects

Revoke an inherited project role from group on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-INHERIT/1.0/rel/project_group_role_inherited_to_projects

Normal response codes: 204

Request¶

Name	In	Type	Description
group_id	path	string	The group ID.
project_id	path	string	The project ID.
role_id	path	string	The role ID.

GET

/v3/role_assignments

List role assignments

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/role_assignments

Optional query parameters:

Name	In	Type	Description
effective (Optional)	query	key-only (no value required)	Returns the effective assignments, including any assignments gained by virtue of group membership.
include_names (Optional)	query	boolean	If set to true, then the names of any entities returned will be include as well as their IDs. Any value other than `0` (including no value) will be interpreted as true. New in version 3.6
include_subtree (Optional)	query	boolean	If set to true, then relevant assignments in the project hierarchy below the project specified in the `scope.project_id` query parameter are also included in the response. Any value other than `0` (including no value) for `include_subtree` will be interpreted as true. New in version 3.6
group_id (Optional)	query	string	Filters the response by a group ID.
role_id (Optional)	query	string	Filters the response by a role ID.
scope.domain.id (Optional)	query	string	Filters the response by a domain ID.
scope.OS-INHERIT:inherited_to (Optional)	query	string	Filters based on role assignments that are inherited. The only value of `inherited_to` that is currently supported is `projects`.
scope.project.id (Optional)	query	string	Filters the response by a project ID.
user_id (Optional)	query	string	Filters the response by a user ID.

Get a list of role assignments.

If no query parameters are specified, then this API will return a list of all role assignments.

{
    "role_assignments": [
        {
            "links": {
                "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "domain": {
                    "id": "161718"
                }
            },
            "user": {
                "id": "313233"
            }
        },
        {
            "group": {
                "id": "101112"
            },
            "links": {
                "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "project": {
                    "id": "456789"
                }
            }
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/role_assignments",
        "previous": null,
        "next": null
    }
}

Since this list is likely to be very long, this API would typically always be used with one of more of the filter queries. Some typical examples are:

GET /v3/role_assignments?user.id={user_id} would list all role assignments involving the specified user.

GET /v3/role_assignments?scope.project.id={project_id} would list all role assignments involving the specified project.

It is also possible to list all role assignments within a tree of projects: GET /v3/role_assignments?scope.project.id={project_id}&include_subtree=true would list all role assignments involving the specified project and all sub-projects. include_subtree=true can only be specified in conjunction with scope.project.id, specifiying it without this will result in an HTTP 400 Bad Request being returned.

Each role assignment entity in the collection contains a link to the assignment that gave rise to this entity.

The scope section in the list response is extended to allow the representation of role assignments that are inherited to projects.

{
        "role_assignments": [
            {
                "links": {
                    "assignment": "http://example.com/identity/v3/OS-INHERIT/domains/161718/users/313233/roles/123456/inherited_to_projects"
                },
                "role": {
                    "id": "123456"
                },
                "scope": {
                    "domain": {
                        "id": "161718"
                    },
                    "OS-INHERIT:inherited_to": "projects"
                },
                "user": {
                    "id": "313233"
                }
            },
            {
                "group": {
                    "id": "101112-"
                },
                "links": {
                    "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456"
                },
                "role": {
                    "id": "123456"
                },
                "scope": {
                    "project": {
                        "id": "456789"
                    }
                }
            }
        ],
        "links": {
            "self": "http://example.com/identity/v3/role_assignments",
            "previous": null,
            "next": null
        }
    }

The query filter scope.OS-INHERIT:inherited_to can be used to filter based on role assignments that are inherited. The only value of scope.OS-INHERIT:inherited_to that is currently supported is projects, indicating that this role is inherited to all projects of the owning domain or parent project.

If the query parameter effective is specified, rather than simply returning a list of role assignments that have been made, the API returns a list of effective assignments at the user, project and domain level, having allowed for the effects of group membership, role inference rules as well as inheritance from the parent domain or project. Since the effects of group membership have already been allowed for, the group role assignment entities themselves will not be returned in the collection. Likewise, since the effects of inheritance have already been allowed for, the role assignment entities themselves that specify the inheritance will also not be returned in the collection. This represents the effective role assignments that would be included in a scoped token. The same set of query parameters can also be used in combination with the effective parameter.

For example:

GET /v3/role_assignments?user.id={user_id}&effective would, in other words, answer the question “what can this user actually do?”.

GET /v3/role_assignments?user.id={user_id}&scope.project.id={project_id}&effective would return the equivalent set of role assignments that would be included in the token response of a project scoped token.

An example response for an API call with the query parameter effective specified is given below:

{
    "role_assignments": [
        {
            "links": {
                "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "domain": {
                    "id": "161718"
                }
            },
            "user": {
                "id": "313233"
            }
        },
        {
            "links": {
                "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456",
                "membership": "http://example.com/identity/v3/groups/101112/users/313233"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "project": {
                    "id": "456789"
                }
            },
            "user": {
                "id": "313234"
            }
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/role_assignments?effective",
        "previous": null,
        "next": null
    }
}

The entity links section of a response using the effective query parameter also contains, for entities that are included by virtue of group membership, a url that can be used to access the membership of the group.

If the query parameter include_names is specified, rather than simply returning the entity IDs in the role assignments, the collection will additionally include the names of the entities. For example:

GET /v3/role_assignments?user.id={user_id}&effective&include_names=true would return:

{
        "role_assignments": [
            {
                "links": {
                    "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456"
                },
                "role": {
                    "domain": {
                        "id": "161718",
                        "name": "Default"
                    },
                    "id": "123456",
                    "name": "admin"
                },
                "scope": {
                    "domain": {
                        "id": "161718",
                        "name": "Default"
                    }
                },
                "user": {
                    "domain": {
                        "id": "161718",
                        "name": "Default"
                    },
                    "id": "313233",
                    "name": "admin"
                }
            },
            {
                "links": {
                    "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456",
                    "membership": "http://example.com/identity/v3/groups/101112/users/313233"
                },
                "role": {
                    "domain": {
                        "id": "161718",
                        "name": "Default"
                    },
                    "id": "123456",
                    "name": "admin"
                },
                "scope": {
                    "project": {
                        "domain": {
                            "id": "161718",
                            "name": "Default"
                        }
                        "id": "456789",
                        "name": "admin"
                    }
                },
                "user": {
                    "domain": {
                        "id": "161718",
                        "name": "Default"
                    },
                    "id": "313233",
                    "name": "admin"
                }
            }
        ],
        "links": {
            "self": "http://example.com/identity/v3/role_assignments?effective&include_names=true",
            "previous": null,
            "next": null
        }
    }

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 405, 413, 503

OS-PKI API¶

GET

/v3/auth/tokens/OS-PKI/revoked

List revoked tokens

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/tokens/OS-PKI/revoked

Lists revoked PKI tokens.

Normal response codes: 200

Error response codes: 413,415,405,404,403,401,400,503,409

Response¶

Name	In	Type	Description
signed	body	string	List of expired PKI tokens, signed by the cryptographic message syntax (CMS).

Response Example¶

{
  "signed": "-----BEGIN CMS-----\nMIICGwYJKoZIhvcNAQcCoIICDDCCAggCAQExDTALBglghkgBZQMEAgEwawYJKoZI\nhvcNAQcBoF4EXHsicmV2b2tlZCI6IFt7ImV4cGlyZXMiOiAiMjAxNC0xMi0wMlQx\nNzowMDowOVoiLCAiaWQiOiAiODhiMjRmOTI5OTk0NGU1ZjhkODE0MDNjYzMyY2M5\nMmUifV19MYIBhTCCAYECAQEwXDBXMQswCQYDVQQGEwJVUzEOMAwGA1UECAwFVW5z\nZXQxDjAMBgNVBAcMBVVuc2V0MQ4wDAYDVQQKDAVVbnNldDEYMBYGA1UEAwwPd3d3\nLmV4YW1wbGUuY29tAgEBMAsGCWCGSAFlAwQCATANBgkqhkiG9w0BAQEFAASCAQA3\nc8EI58ZXtqkyuUWqLPJZdB5v7Ou978w22YkOsgL5ruUpQiWdhdgvL/sxqd7OPqi7\nZZV3N+io+z1m4uAiSbriumv7HOEnIUEAUhK4G0kw5kAAg4j50c0Omdiqdq75k0j/\nJPoRCXa8ieb0X87zhgfIq7ze/HZ7E2LoO20us3AEzmglNv023qgGcsSGPAUIHWN5\nloonPtgztiwVbmS2gs3Z9JB73mxEBviCX4CZEU/sNpchAzI/53tscKlqlzv+GBcm\n1dYP3hEZn3twFRI9zos4hTwFkUivn6D3qgQB684sVrvKlzOCIqOKVGGYVSy/FQLE\nWwQ5u58ZD8ohaJPu2Q6l\n-----END CMS-----\n"
}

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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/policies

Creates a policy.

Normal response codes: 201

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
policy	body	object	A `policy` object.
type	body	string	The MIME media type of the serialized policy blob.
blob	body	string	The policy rule set itself, as a serialized blob.

Request Example¶

{
    "policy": {
        "blob": "{'foobar_user': 'role:compute-user'}",
        "type": "application/json"
    }
}

Response Parameters¶

Name	In	Type	Description
links	body	object	The links for the `policy` resource.
blob	body	string	The policy rule set itself, as a serialized blob.
policy	body	object	A `policy` object.
type	body	string	The MIME media type of the serialized policy blob.
id	body	string	The policy ID.

GET

/v3/policies

List policies

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/policies

Lists policies.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
type (Optional)	query	string	Filters the response by a MIME media type for the serialized policy blob. For example, `application/json`.

Response Parameters¶

Name	In	Type	Description
links	body	object	The links for the `policy` resource.
blob	body	object	The policy rule itself, as a serialized blob.
policies	body	array	A `policies` object.
type	body	string	The MIME media type of the serialized policy blob.
id	body	string	The policy ID.

Response Example¶

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/policies"
    },
    "policies": [
        {
            "blob": {
                "foobar_user": [
                    "role:compute-user"
                ]
            },
            "id": "717273",
            "links": {
                "self": "http://example.com/identity/v3/policies/717273"
            },
            "type": "application/json"
        },
        {
            "blob": {
                "foobar_user": [
                    "role:compute-user"
                ]
            },
            "id": "717274",
            "links": {
                "self": "http://example.com/identity/v3/policies/717274"
            },
            "type": "application/json"
        }
    ]
}

GET

/v3/policies/{policy_id}

Show policy details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/policy

Shows details for a policy.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
policy_id	path	string	The policy ID.

Response Parameters¶

Name	In	Type	Description
links	body	object	The links for the `policy` resource.
blob	body	object	The policy rule itself, as a serialized blob.
policy	body	object	A `policy` object.
type	body	string	The MIME media type of the serialized policy blob.
id	body	string	The policy ID.

Response Example¶

{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "id": "717273",
        "links": {
            "self": "http://example.com/identity/v3/policies/717273"
        },
        "type": "application/json"
    }
}

PATCH

/v3/policies/{policy_id}

Update policy

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/policy

Updates a policy.

Normal response codes: 200

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
policy_id	path	string	The policy ID.
policy	body	object	A `policy` object.
type	body	string	The MIME media type of the serialized policy blob.
blob	body	object	The policy rule itself, as a serialized blob.

Request Example¶

{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "type": "application/json"
    }
}

Response Parameters¶

Name	In	Type	Description
links	body	object	The links for the `policy` resource.
blob	body	object	The policy rule itself, as a serialized blob.
policy	body	object	A `policy` object.
type	body	string	The MIME media type of the serialized policy blob.
id	body	string	The policy ID.

Response Example¶

{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "id": "717273",
        "links": {
            "self": "http://example.com/identity/v3/policies/717273"
        },
        "type": "application/json"
    }
}

DELETE

/v3/policies/{policy_id}

Delete policy

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/policy

Deletes a policy.

Normal response codes: 204

Error response codes: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
policy_id	path	string	The policy ID.

Projects¶

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

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

(Since Identity API v3.6) Projects may, in addition to acting as containers for OpenStack resources, act as a domain (by setting the attribute is_domain to true), in which case it provides a namespace in which users, groups and other projects can be created. In fact, a domain created using the POST /domains API will actually be represented as a project with is_domain set to true with no parent (parent_id is null).

Given this, all projects are considered part of a project hierarchy. Projects created in a domain prior to v3.6 are represented as a two-level hierarchy, with a project that has is_domain set to true as the root and all other projects referencing the root as their parent.

A project acting as a domain can potentially also act as a container for OpenStack resources, although this depends on whether the policy rule for the relevant resource creation allows this.

Note

A project’s name must be unique within a domain and no more than 64 characters. A project’s name must be able to be sent within valid JSON, which could be any UTF-8 character. However, this is constrained to the given backend where project names are stored. For instance, MySQL’s restrictions states that UTF-8 support is constrained to the characters in the Basic Multilingual Plane (BMP). Supplementary characters are not permitted. Note that this last restriction is generally true for all names within resources of the Identity API.

GET

/v3/projects

List projects

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/projects

Lists projects.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
domain_id (Optional)	query	string	Filters the response by a domain ID.
enabled (Optional)	query	boolean	If set to true, then only enabled projects will be returned. Any value other than `0` (including no value) will be interpreted as true.
is_domain (Optional)	query	boolean	If this is specified as true, then only projects acting as a domain are included. Otherwise, only projects that are not acting as a domain are included. New in version 3.6
name (Optional)	query	string	Filters the response by a project name.
parent_id (Optional)	query	string	Filters the response by a parent ID. New in version 3.4

Response Parameters¶

Name	In	Type	Description
links	body	object	The link to the collection of resources.
projects	body	array	A list of `project` objects, each containing:
is_domain	body	boolean	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. If set to `false`, this project behaves as a regular project that contains only resources. New in version 3.6
description	body	string	The description of the project.
domain_id	body	string	The ID of the domain for the project.
enabled	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled.
id	body	string	The ID for the project.
links	body	object	The link to the resources in question.
name	body	string	The name of the project.
parent_id	body	string	The ID of the parent for the project. New in version 3.4

Response Example¶

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

POST

/v3/projects

Create project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/projects

Creates a project, where the project may act as a domain.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
project	body	object	A `project` object, containing:
is_domain (Optional)	body	boolean	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. If set to `false`, this project behaves as a regular project that contains only resources. Default is `false`. You cannot update this parameter after you create the project. New in version 3.6
description (Optional)	body	string	The description of the project.
domain_id (Optional)	body	string	The ID of the domain for the project. For projects acting as a domain, the `domain_id` must not be specified, it will be generated by the Identity service implementation. For regular projects (i.e. those not acing as a domain), if `domain_id` is not specified, but `parent_id` is specified, then the domain ID of the parent will be used. If neither `domain_id` or `parent_id` is specified, the Identity service implementation will default to the domain to which the client’s token is scoped. If both `domain_id` and `parent_id` are specified, and they do not indicate the same domain, an `Bad Request (400)` will be returned.
enabled (Optional)	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled. The default is `true`.
name	body	string	The name of the project, which must be unique within the owning domain. A project can have the same name as its domain.
parent_id (Optional)	body	string	The ID of the parent of the project. If specified on project creation, this places the project within a hierarchy and implicitly defines the owning domain, which will be the same domain as the parent specified. If `parent_id` is not specified and `is_domain` is `false`, then the project will use its owning domain as its parent. If `is_domain` is `true` (i.e. the project is acting as a domain), then `parent_id` must not specified (or if it is, it must be `null`) since domains have no parents. `parent_id` is immutable, and can’t be updated after the project is created - hence a project cannot be moved within the hierarchy. New in version 3.4

Request Examples¶

Sample for creating a regular project:

{
    "project": {
        "description": "My new project",
        "domain_id": "default",
        "enabled": true,
        "is_domain": false,
        "name": "myNewProject"
    }
}

Sample for creating a project that also acts as a domain:

{
    "project": {
        "description": "My new domain",
        "enabled": true,
        "is_domain": true,
        "name": "myNewDomain"
    }
}

Response Parameters¶

Name	In	Type	Description
project	body	object	A `project` object, containing:
is_domain	body	boolean	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. If set to `false`, this project behaves as a regular project that contains only resources. New in version 3.6
description	body	string	The description of the project.
domain_id	body	string	The ID of the domain for the project.
enabled	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled.
id	body	string	The ID for the project.
links	body	object	The link to the resources in question.
name	body	string	The name of the project.
parent_id	body	string	The ID of the parent for the project. New in version 3.4

GET

/v3/projects/{project_id}

Show project details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project

Shows details for a project.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
parents_as_list (Optional)	query	key-only, no value expected	The parent hierarchy will be included as a list in the response. This list will contain the projects found by traversing up the hierarchy to the top-level project. The returned list will be filtered against the projects the user has an effective role assignment on. New in version 3.4
subtree_as_list (Optional)	query	key-only, no value expected	The child hierarchy will be included as a list in the response. This list will contain the projects found by traversing down the hierarchy. The returned list will be filtered against the projects the user has an effective role assignment on. New in version 3.4
parents_as_ids (Optional)	query	key-only, no value expected	The entire parent hierarchy will be included as nested dictionaries in the response. It will contain all projects ids found by traversing up the hierarchy to the top-level project. New in version 3.4
subtree_as_ids (Optional)	query	key-only, no value expected	The entire child hierarchy will be included as nested dictionaries in the response. It will contain all the projects ids found by traversing down the hierarchy. New in version 3.4

Response Parameters¶

Name	In	Type	Description
project	body	object	A `project` object, containing:
is_domain	body	boolean	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. If set to `false`, this project behaves as a regular project that contains only resources. New in version 3.6
description	body	string	The description of the project.
domain_id	body	string	The ID of the domain for the project.
enabled	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled.
id	body	string	The ID for the project.
links	body	object	The link to the resources in question.
name	body	string	The name of the project.
parent_id	body	string	The ID of the parent for the project. New in version 3.4

Response Example¶

{
    "project": {
        "is_domain": false,
        "description": null,
        "domain_id": "default",
        "enabled": true,
        "id": "0c4e939acacf4376bdcd1129f1a054ad",
        "links": {
            "self": "http://example.com/identity/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
        },
        "name": "admin",
        "parent_id": "default"
    }
}

Response Example with `parents_as_list`¶

{
    "project": {
        "domain_id": "1789d1",
        "enabled": true,
        "id": "263fd9",
        "links": {
            "self": "http://example.com/identity/v3/projects/263fd9"
        },
        "name": "Dev Group A",
        "parent_id": "183ab2",
        "parents": [
            {
                "project": {
                    "domain_id": "1789d1",
                    "enabled": true,
                    "id": "183ab2",
                    "links": {
                        "self": "http://example.com/identity/v3/projects/183ab2"
                    },
                    "name": "Dev Group A Parent",
                    "parent_id": null
                }
            }
        ]
    }
}

Response Example with `subtree_as_list`¶

{
    "project": {
        "domain_id": "1789d1",
        "enabled": true,
        "id": "263fd9",
        "links": {
            "self": "http://example.com/identity/v3/projects/263fd9"
        },
        "name": "Dev Group A",
        "parent_id": "183ab2",
        "subtree": [
            {
                "project": {
                    "domain_id": "1789d1",
                    "enabled": true,
                    "id": "9n1jhb",
                    "links": {
                        "self": "http://example.com/identity/v3/projects/9n1jhb"
                    },
                    "name": "Dev Group A Child 1",
                    "parent_id": "263fd9"
                }
            },
            {
                "project": {
                    "domain_id": "1789d1",
                    "enabled": true,
                    "id": "4b6aa1",
                    "links": {
                        "self": "http://example.com/identity/v3/projects/4b6aa1"
                    },
                    "name": "Dev Group A Child 2",
                    "parent_id": "263fd9"
                }
            },
            {
                "project": {
                    "domain_id": "1789d1",
                    "enabled": true,
                    "id": "b76eq8",
                    "links": {
                        "self": "http://example.com/identity/v3/projects/b76xq8"
                    },
                    "name": "Dev Group A Grandchild",
                    "parent_id": "4b6aa1"
                }
            }
        ]
    }
}

PATCH

/v3/projects/{project_id}

Update project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project

Updates a project.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
project	body	object	A `project` object, containing:
is_domain (Optional)	body	boolean	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. If set to `false`, this project behaves as a regular project that contains only resources. Default is `false`. You cannot update this parameter after you create the project. New in version 3.6
description (Optional)	body	string	The description of the project.
domain_id (Optional)	body	string	The ID of the new domain for the project. The ability to change the domain of a project is now deprecated, and will be removed in subequent release. It is already disabled by default in most Identity service implementations.
enabled (Optional)	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled.
name (Optional)	body	string	The name of the project, which must be unique within the owning domain. A project can have the same name as its domain.

Request Example¶

{
    "project": {
        "description": "My updated project",
        "name": "myUpdatedProject"
    }
}

Response Parameters¶

Name	In	Type	Description
project	body	object	A `project` object, containing:
is_domain	body	boolean	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. If set to `false`, this project behaves as a regular project that contains only resources. New in version 3.6
description	body	string	The description of the project.
domain_id	body	string	The ID of the domain for the project.
enabled	body	boolean	If set to `true`, project is enabled. If set to `false`, project is disabled.
id	body	string	The ID for the project.
name	body	string	The name of the project.
links	body	object	The link to the resources in question.
parent_id	body	string	The ID of the parent for the project. New in version 3.4

Response Example¶

{
    "project": {
        "description": "My updated project",
        "domain_id": null,
        "links": {
            "self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
        },
        "enabled": true,
        "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
        "is_domain": true,
        "name": "myUpdatedProject"
        "parent_id": null,
    }
}

DELETE

/v3/projects/{project_id}

Delete project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project

Deletes a project.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.

Regions¶

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 ID, such as us- east.

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

GET

/v3/regions/{region_id}

Show region details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/regions

Shows details for a region, by ID.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
region_id	path	string	The region ID.

Response Parameters¶

Name	In	Type	Description
region	body	object	A `region` object, containing the following:
description	body	string	The region description.
id	body	string	The ID for the region.
links	body	object	The links for the `region` resource.
parent_region_id	body	string	To make this region a child of another region, set this parameter to the ID of the parent region.

Response Example¶

{
    "region": {
        "description": "My subregion 3",
        "id": "RegionThree",
        "links": {
            "self": "http://example.com/identity/v3/regions/RegionThree"
        },
        "parent_region_id": "RegionOne"
    }
}

PATCH

/v3/regions/{region_id}

Update region

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
region_id	path	string	The region ID.
region	body	object	A `region` object, containing the following:
description (Optional)	body	string	The region description.
parent_region_id (Optional)	body	string	To make this region a child of another region, set this parameter to the ID of the parent region.

Request Example¶

{
    "region": {
        "description": "My subregion 3"
    }
}

Response Parameters¶

Name	In	Type	Description
region	body	object	A `region` object, containing the following:
description	body	string	The region description.
id	body	string	The ID for the region.
links	body	object	The links for the `region` resource.
parent_region_id	body	string	To make this region a child of another region, set this parameter to the ID of the parent region.

Response Example¶

{
    "region": {
        "parent_region_id": "RegionOne",
        "id": "RegionThree",
        "links": {
            "self": "http://example.com/identity/v3/regions/RegionThree"
        },
        "description": "My subregion 3"
    }
}

DELETE

/v3/regions/{region_id}

Delete region

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
region_id	path	string	The region ID.

GET

/v3/regions

List regions

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/regions

Lists regions.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request¶

Name	In	Type	Description
parent_region_id (Optional)	query	string	Filters the response by a parent region, by ID.

Response Parameters¶

Name	In	Type	Description
regions	body	array	A list of `region` object, each containing the following:
description	body	string	The region description.
id	body	string	The ID for the region.
links	body	object	The links for the `region` resource.
parent_region_id	body	string	To make this region a child of another region, set this parameter to the ID of the parent region.

Response Example¶

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/regions"
    },
    "regions": [
        {
            "description": "",
            "id": "RegionOne",
            "links": {
                "self": "http://example.com/identity/v3/regions/RegionOne"
            },
            "parent_region_id": null
        }
    ]
}

POST

/v3/regions

Create region

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/regions

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: 413,415,405,404,403,401,400,503,409

Request¶

Name	In	Type	Description
region	body	object	A `region` object, containing the following:
description (Optional)	body	string	The region description.
id (Optional)	body	string	The ID for the region.
parent_region_id (Optional)	body	string	To make this region a child of another region, set this parameter to the ID of the parent region.

Request Example¶

{
    "region": {
        "description": "My subregion",
        "id": "RegionOneSubRegion",
        "parent_region_id": "RegionOne"
    }
}

Response Parameters¶

Name	In	Type	Description
region	body	object	A `region` object, containing the following:
description	body	string	The region description.
id	body	string	The ID for the region.
links	body	object	The links for the `region` resource.
parent_region_id	body	string	To make this region a child of another region, set this parameter to the ID of the parent region.

Roles¶

OpenStack services typically determine whether a user’s API request should be allowed using Role Based Access Control (RBAC). For OpenStack this means the service compares the roles that user has on the project (as indicated by the roles in the token), against the roles required for the API in question (as defined in the service’s policy file). A user obtains roles on a project by having these assigned to them via the Identity service API.

Roles must initially be created as entities via the Identity services API and, once created, can then be assigned. You can assign roles to a user or group on a project, including projects owned by other domains. You can also assign roles to a user or group on a domain, although this is only currently relevant for using a domain scoped token to execute domain-level Identity service API requests.

The creation, checking and deletion of role assignments is done with each of the attributes being specified in the URL. For example to assign a role to a user on a project:

PUT /v3/projects/{project_id}/users/{user_id}/roles/{role_id}

You can also list roles assigned to a specified domain, project, or user using this form of API, however a more generalized API for list assignments is provided where query parameters are used to filter the set of assignments returned in the collection. For example:

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}

Since Identity API v3.6, you can also list all role assignments within a tree of projects, for example the following would 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.

As mentioned earlier, role assignments can be made to a user or a group on a particular project or domain. A user who is a member of a group that has a role assignment, will also be treated as having that role assignment by virtue of their group membership. The effective role assignments of a user (on a given project or domain) therefore consists of any direct assignments they have, plus any they gain by virtue of membership of groups that also have assignments on the given project or domain. This set of effective role assignments is what is placed in the token for reference by services wishing to check policy. You can list the effective role assignments using the effective query parameter at the user, project, and domain level:

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
```

When listing in effective mode, since the group assignments have been effectively expanded out into assignments for each user, the group role assignment entities themselves are not returned in the collection. However, in the response, the links entity section for each assignment gained by virtue of group membership will contain a URL that enables access to the membership of the group.

By default only the IDs of entities are returned in collections from the role_assignment API calls. The names of entities may also be returned, in addition to the IDs, by using the include_names query parameter on any of these calls, for example:

List role assignments including names:
```
GET /role_assignments?include_names
```

GET

/v3/roles

List roles

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/roles

Lists roles.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
name (Optional)	query	string	Filters the response by a role name.
domain_id (Optional)	query	string	Filters the response by a domain ID.

Response Parameters¶

Name	In	Type	Description
links	body	object	The link to the collection of resources.
roles	body	array	A list of `role` objects, each containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/roles"
    },
    "roles": [
        {
            "id": "5318e65d75574c17bf5339d3df33a5a3",
            "links": {
                "self": "http://example.com/identity/v3/roles/5318e65d75574c17bf5339d3df33a5a3"
            },
            "name": "admin"
        },
        {
            "id": "642bcfc75c384fd181adf34d9b2df897",
            "links": {
                "self": "http://example.com/identity/v3/roles/642bcfc75c384fd181adf34d9b2df897"
            },
            "name": "anotherrole"
        },
        {
            "id": "779a76d74f544224a7ef8762ca0de627",
            "links": {
                "self": "http://example.com/identity/v3/roles/779a76d74f544224a7ef8762ca0de627"
            },
            "name": "Member"
        },
        {
            "id": "9fe2ff9ee4384b1894a90878d3e92bab",
            "links": {
                "self": "http://example.com/identity/v3/roles/9fe2ff9ee4384b1894a90878d3e92bab"
            },
            "name": "_member_"
        },
        {
            "id": "ba2dfba61c934ee89e3110de36273229",
            "links": {
                "self": "http://example.com/identity/v3/roles/ba2dfba61c934ee89e3110de36273229"
            },
            "name": "ResellerAdmin"
        },
        {
            "id": "f127b97616f24d3ebceb7be840210adc",
            "links": {
                "self": "http://example.com/identity/v3/roles/f127b97616f24d3ebceb7be840210adc"
            },
            "name": "service"
        }
    ]
}

POST

/v3/roles

Create role

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/roles

Creates a role.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
role	body	object	A `role` object, containing:
name	body	string	The role name.
domain_id	body	string	The ID of the domain.

Request Example¶

{
    "role": {
        "name": "developer"
    }
}

Request Example for Domain Specific Role¶

{
    "role": {
        "domain_id": "92e782c4988642d783a95f4a87c3fdd7",
        "name": "developer"
    }
}

Response Parameters¶

Name	In	Type	Description
role	body	object	A `role` object, containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

GET

/v3/roles/{role_id}

Show role details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/role

Shows details for a role.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
role_id	path	string	The role ID.

Response Parameters¶

Name	In	Type	Description
role	body	object	A `role` object, containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "role": {
        "domain_id": "d07792fd66ac4ed881723ab9f1c9925f",
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "name": "Developer"
    }
}

PATCH

/v3/roles/{role_id}

Update role

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/role

Updates a role.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
role_id	path	string	The role ID.
role	body	object	A `role` object, containing:
name (Optional)	body	string	The new role name.

Request Example¶

{
    "role": {
        "name": "Developer"
    }
}

Response Parameters¶

Name	In	Type	Description
role	body	object	A `role` object, containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "role": {
        "domain_id": "73748865fb964ded9e836d491d32dcfb",
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "name": "Developer"
    }
}

DELETE

/v3/roles/{role_id}

Delete role

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/role

Deletes a role.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
role_id	path	string	The role ID.

GET

/v3/domains/{domain_id}/groups/{group_id}/roles

List role assignments for group on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_group_roles

Lists role assignments for a group on a domain.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.

Response Example¶

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

The functionality of this request can also be achieved using the generalized list assignments API:

GET /role_assignments?group.id={group_id}&scope.domain.id={domain_id}

PUT

/v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}

Assign role to group on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_group_role

Assigns a role to a group on a domain.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

HEAD

/v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}

Check whether group has role assignment on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_group_role

Validates that a group has a role assignment on a domain.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

DELETE

/v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}

Unassign role from group on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_group_role

Unassigns a role from a group on a domain.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

GET

/v3/domains/{domain_id}/users/{user_id}/roles

List role assignments for user on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_user_roles

Lists role assignments for a user on a domain.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
user_id	path	string	The user ID.

Response Parameters¶

Name	In	Type	Description
roles	body	array	A list of `role` objects, each containing:
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

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

The functionality of this request can also be achieved using the generalized list assignments API:

GET /role_assignments?user.id={user_id}&scope.domain.id={domain_id}

PUT

/v3/domains/{domain_id}/users/{user_id}/roles/{role_id}

Assign role to user on domain

Relationship: https://developer.openstack.org/api-ref/identity/v3/index.html#assign-role-to-user-on-domain

Assigns a role to a user on a domain.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
user_id	path	string	The user ID.
role_id	path	string	The role ID.

HEAD

/v3/domains/{domain_id}/users/{user_id}/roles/{role_id}

Check whether user has role assignment on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_user_role

Validates that a user has a role assignment on a domain.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
user_id	path	string	The user ID.
role_id	path	string	The role ID.

DELETE

/v3/domains/{domain_id}/users/{user_id}/roles/{role_id}

Unassigns role from user on domain

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/domain_user_role

Unassigns a role from a user on a domain.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
domain_id	path	string	The domain ID.
user_id	path	string	The user ID.
role_id	path	string	The role ID.

GET

/v3/projects/{project_id}/groups/{group_id}/roles

List role assignments for group on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_user_role

Lists role assignments for a group on a project.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
group_id	path	string	The group ID.

Response Example¶

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

The functionality of this request can also be achieved using the generalized list assignments API:

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

PUT

/v3/projects/{project_id}/groups/{group_id}/roles/{role_id}

Assign role to group on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_group_role

Assigns a role to a group on a project.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

HEAD

/v3/projects/{project_id}/groups/{group_id}/roles/{role_id}

Check whether group has role assignment on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_group_role

Validates that a group has a role assignment on a project.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

DELETE

/v3/projects/{project_id}/groups/{group_id}/roles/{role_id}

Unassign role from group on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_group_role

Unassigns a role from a group on a project.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
group_id	path	string	The group ID.
role_id	path	string	The role ID.

GET

/v3/projects/{project_id}/users/{user_id}/roles

List role assignments for user on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_user_role

Lists role assignments for a user on a project.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
user_id	path	string	The user ID.

Response Example¶

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

PUT

/v3/projects/{project_id}/users/{user_id}/roles/{role_id}

Assign role to user on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_user_role

Assigns a role to a user on a project.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
user_id	path	string	The user ID.
role_id	path	string	The role ID.

HEAD

/v3/projects/{project_id}/users/{user_id}/roles/{role_id}

Check whether user has role assignment on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_user_role

Validates that a user has a role on a project.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
user_id	path	string	The user ID.
role_id	path	string	The role ID.

DELETE

/v3/projects/{project_id}/users/{user_id}/roles/{role_id}

Unassign role from user on project

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/project_user_role

Unassigns a role from a user on a project.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
project_id	path	string	The project ID.
user_id	path	string	The user ID.
role_id	path	string	The role ID.

GET

/v3/roles/{prior_role_id}/implies

List implied (inference) roles for role

Lists implied (inference) roles for a role.

Relationship: https://developer.openstack.org/api-ref/identity/v3/#list-implied-roles-for-role

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
prior_role_id	path	string	Role ID for a prior role.

Response Parameters¶

Name	In	Type	Description
role_inference	body	object	Role inference object that contains `prior_role` object and `implies` object.
prior_role	body	object	A prior role object.
implies	body	array	An array of implied role objects.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "role_inference": {
        "prior_role": {
            "id": "42c764f0c19146728dbfe73a49cc35c3",
            "links": {
                "self": "http://example.com/identity/v3/roles/42c764f0c19146728dbfe73a49cc35c3"
            },
            "name": "prior role name"
        },
        "implies": [
            {
                "id": "066fbfc8b3e54fb68784c9e7e92ab8d7",
                "links": {
                    "self": "http://example.com/identity/v3/roles/066fbfc8b3e54fb68784c9e7e92ab8d7"
                },
                "name": "implied role1 name"
            },
            {
                "id": "32a0df1cc22848aca3986adae9e0b9a0",
                "links": {
                    "self": "http://example.com/identity/v3/roles/32a0df1cc22848aca3986adae9e0b9a0"
                },
                "name": "implied role2 name"
            }
        ]
    },
    "links" : {
        "self": "http://example.com/identity/v3/roles/42c764f0c19146728dbfe73a49cc35c3/implies"
    }
}

PUT

/v3/roles/{prior_role_id}/implies/{implies_role_id}

Create role inference rule

Creates a role inference rule.

Relationship: https://developer.openstack.org/api-ref/identity/v3/#create-role-inference-rule

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
prior_role_id	path	string	Role ID for a prior role.
implies_role_id	path	string	Role ID for an implied role.

Response Parameters¶

Name	In	Type	Description
role_inference	body	object	Role inference object that contains `prior_role` object and `implies` object.
prior_role	body	object	A prior role object.
implies	body	object	An implied role object.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "role_inference": {
        "prior_role": {
            "id": "7ceab6192ea34a548cc71b24f72e762c",
            "links": {
                "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c"
            },
            "name": "prior role name"
        },
        "implies": {
            "id": "97e2f5d38bc94842bc3da818c16762ed",
            "links": {
                "self": "http://example.com/identity/v3/roles/97e2f5d38bc94842bc3da818c16762ed"
            },
            "name": "implied role name"
        }
    },
    "links": {
        "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c/implies/97e2f5d38bc94842bc3da818c16762ed"
    }
}

GET

/v3/roles/{prior_role_id}/implies/{implies_role_id}

Get role inference rule

Gets a role inference rule.

Relationship: https://developer.openstack.org/api-ref/identity/v3/#get-role-inference-rule

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
prior_role_id	path	string	Role ID for a prior role.
implies_role_id	path	string	Role ID for an implied role.

Response Parameters¶

Name	In	Type	Description
role_inference	body	object	Role inference object that contains `prior_role` object and `implies` object.
prior_role	body	object	A prior role object.
implies	body	object	An implied role object.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "role_inference": {
        "prior_role": {
            "id": "7ceab6192ea34a548cc71b24f72e762c",
            "links": {
                "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c"
            },
            "name": "prior role name"
        },
        "implies": {
            "id": "97e2f5d38bc94842bc3da818c16762ed",
            "links": {
                "self": "http://example.com/identity/v3/roles/97e2f5d38bc94842bc3da818c16762ed"
            },
            "name": "implied role name"
        }
    },
    "links": {
        "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c/implies/97e2f5d38bc94842bc3da818c16762ed"
    }
}

HEAD

/v3/roles/{prior_role_id}/implies/{implies_role_id}

Confirm role inference rule

Checks a role role inference rule.

Relationship: https://developer.openstack.org/api-ref/identity/v3/#confirm-role-inference-rule

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
prior_role_id	path	string	Role ID for a prior role.
implies_role_id	path	string	Role ID for an implied role.

Response Example¶

Status: 204 No Content

DELETE

/v3/roles/{prior_role_id}/implies/{implies_role_id}

Delete role inference rule

Deletes a role inference rule.

Relationship: https://developer.openstack.org/api-ref/identity/v3/#delete-role-inference-rule

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
prior_role_id	path	string	Role ID for a prior role.
implies_role_id	path	string	Role ID for an implied role.

Response Example¶

Status: 204 No Content

GET

/v3/role_assignments

List role assignments

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/role_assignments

Lists role assignments.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
effective (Optional)	query	key-only (no value required)	Returns the effective assignments, including any assignments gained by virtue of group membership.
include_names (Optional)	query	boolean	If set to true, then the names of any entities returned will be include as well as their IDs. Any value other than `0` (including no value) will be interpreted as true. New in version 3.6
include_subtree (Optional)	query	boolean	If set to true, then relevant assignments in the project hierarchy below the project specified in the `scope.project_id` query parameter are also included in the response. Any value other than `0` (including no value) for `include_subtree` will be interpreted as true. New in version 3.6
group.id (Optional)	query	string	Filters the response by a group ID.
role.id (Optional)	query	string	Filters the response by a role ID.
scope.domain.id (Optional)	query	string	Filters the response by a domain ID.
scope.project.id (Optional)	query	string	Filters the response by a project ID.
user.id (Optional)	query	string	Filters the response by a user ID.

Response Parameters¶

Name	In	Type	Description
role_assignments	body	array	A list of `role_assignment` objects.

Response Example¶

{
    "role_assignments": [
        {
            "links": {
                "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "domain": {
                    "id": "161718"
                }
            },
            "user": {
                "id": "313233"
            }
        },
        {
            "group": {
                "id": "101112"
            },
            "links": {
                "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456"
            },
            "role": {
                "id": "123456"
            },
            "scope": {
                "project": {
                    "id": "456789"
                }
            }
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/role_assignments",
        "previous": null,
        "next": null
    }
}

GET

/v3/role_inferences

List all role inference rules

Lists all role inference rules.

Relationship: https://developer.openstack.org/api-ref/identity/v3/#list-all-role-inference-rules

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.
`404 - Not Found`	The requested resource could not be found.

Response Parameters¶

Name	In	Type	Description
role_inferences	body	array	An array of `role_inference` object.
prior_role	body	object	A prior role object.
implies	body	object	An implied role object.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Response Example¶

{
    "role_inferences": [
        {
            "prior_role": {
                "id": "1acd3c5aa0e246b9a7427d252160dcd1",
                "links": {
                    "self": "http://example.com/identity/v3/roles/1acd3c5aa0e246b9a7427d252160dcd1"
                },
                "name": "prior role name"
            },
            "implies": [
                {
                    "id": "3602510e2e1f499589f78a0724dcf614",
                    "links": {
                        "self": "http://example.com/identity/v3/roles/3602510e2e1f499589f78a0724dcf614"
                    },
                    "name": "implied role1 name"
                },
                {
                    "id": "738289aeef684e73a987f7cf2ec6d925",
                    "links": {
                        "self": "http://example.com/identity/v3/roles/738289aeef684e73a987f7cf2ec6d925"
                    },
                    "name": "implied role2 name"
                }
            ]
        },
        {
            "prior_role": {
                "id": "bbf7a5098bb34407b7164eb6ff9f144e",
                "links": {
                    "self" : "http://example.com/identity/v3/roles/bbf7a5098bb34407b7164eb6ff9f144e"
                },
                "name": "prior role name"
            },
            "implies": [
                {
                    "id": "872b20ad124c4c1bafaef2b1aae316ab",
                    "links": {
                        "self": "http://example.com/identity/v3/roles/872b20ad124c4c1bafaef2b1aae316ab"
                    },
                    "name": "implied role1 name"
                },
                {
                    "id": "1d865b1b2da14cb7b05254677e5f36a2",
                    "links": {
                        "self": "http://example.com/identity/v3/roles/1d865b1b2da14cb7b05254677e5f36a2"
                    },
                    "name": "implied role2 name"
                }
            ]
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/role_inferences"
    }
}

Service catalog and endpoints¶

A service is an OpenStack web service that you can access through a URL, i.e. an 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

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/services

Lists all services.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
type (Optional)	query	string	Filters the response by a service type. A valid value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.

Response Parameters¶

Name	In	Type	Description
name	body	string	The service name.
links	body	object	The links for the `service` resource.
enabled	body	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.
services	body	array	A list of `service` object.
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
id	body	string	The UUID of the service to which the endpoint belongs.
description	body	string	The service description.

Response Example¶

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

POST

/v3/services

Create service

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/services

Creates a service.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
description	body	string	The service description.
service	body	object	A `service` object.
enabled	body	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.
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
name	body	string	The service name.

Request Example¶

{
    "service": {
        "type": "compute",
        "name": "compute2",
        "description": "Compute service 2"
    }
}

Response Parameters¶

Name	In	Type	Description
name	body	string	The service name.
service	body	object	A `service` object.
links	body	object	The links for the `service` resource.
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
id	body	string	The UUID of the service to which the endpoint belongs.
description	body	string	The service description.

GET

/v3/services/{service_id}

Show service details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/service

Shows details for a service.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
service_id	path	string	The service ID.

Response Parameters¶

Name	In	Type	Description
name	body	string	The service name.
service	body	object	A `service` object.
links	body	object	The links for the `service` resource.
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
id	body	string	The UUID of the service to which the endpoint belongs.
description	body	string	The service description.

Response Example¶

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

PATCH

/v3/services/{service_id}

Update service

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/services

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.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
enabled (Optional)	body	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`.
description (Optional)	body	string	The service description.
service	body	object	A `service` object.
name	body	string	The service name.
service_id	path	string	The service ID.

Request Example¶

{
    "service": {
        "description": "Block Storage Service V2"
    }
}

Response Parameters¶

Name	In	Type	Description
name	body	string	The service name.
service	body	object	A `service` object.
links	body	object	The links for the `service` resource.
type	body	string	The service type, which describes the API implemented by the service. Value is `compute`, `ec2`, `identity`, `image`, `network`, or `volume`.
id	body	string	The UUID of the service to which the endpoint belongs.
description	body	string	The service description.

Response Example¶

{
    "service": {
        "name": "cinderv2",
        "links": {
            "self": "http://example.com/identity/v3/services/5789da9864004dd088fce14c1c626a4b"
        },
        "enabled": true,
        "type": "volumev2",
        "id": "5789da9864004dd088fce14c1c626a4b",
        "description": "Block Storage Service V2"
    }
}

DELETE

/v3/services/{service_id}

Delete service

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/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.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
service_id	path	string	The service ID.

GET

/v3/endpoints

List endpoints

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/endpoints

Lists all available endpoints.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
interface (Optional)	query	string	Filters the response by an interface.
service_id (Optional)	query	string	Filters the response by a service ID.

Response Parameters¶

Name	In	Type	Description
region_id	body	string	(Since v3.2) The ID of the region that contains the service endpoint.
links	body	object	The links for the `endpoints` resource.
url	body	string	The endpoint URL.
region	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
enabled	body	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	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
service_id	body	string	The UUID of the service to which the endpoint belongs.
endpoints	body	array	A list of `endpoint` objects.
id	body	string	The endpoint ID.

Response Example¶

{
    "endpoints": [
        {
            "enabled": true,
            "id": "0649c5be323f4792afbc1efdd480847d",
            "interface": "internal",
            "links": {
                "self": "http://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/v3/endpoints/7cffc75a14ca4334b458e475750bd84f"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "efeb249cbcd3412496bc4b194ea058da",
            "url": "http://example.com/identity/v2.0"
        },
        {
            "enabled": true,
            "id": "a422a6fa163b4a6ba8309e067ce3750b",
            "interface": "public",
            "links": {
                "self": "http://example.com/identity/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://example.com/identity/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://example.com/identity/v3/endpoints/adf43d7ff0d14d0fa1e8a5187f40e1af"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "efeb249cbcd3412496bc4b194ea058da",
            "url": "http://example.com/identity/v2.0"
        },
        {
            "enabled": true,
            "id": "b18be64a118244d39217db72534f8b33",
            "interface": "admin",
            "links": {
                "self": "http://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/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://example.com/identity/v3/endpoints/d8e0824a17404431b5d978a87ac1bede"
            },
            "region": "RegionOne",
            "region_id": "RegionOne",
            "service_id": "efeb249cbcd3412496bc4b194ea058da",
            "url": "http://example.com/identity_v2_admin/v2.0"
        },
        {
            "enabled": true,
            "id": "d9b54bdc063046828ac3c6487bea8047",
            "interface": "internal",
            "links": {
                "self": "http://example.com/identity/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://example.com/identity/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://example.com/identity/v3/endpoints"
    }
}

POST

/v3/endpoints

Create endpoint

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/endpoints

Creates an endpoint.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
endpoint	body	object	An `endpoint` object.
url	body	string	The endpoint URL.
enabled (Optional)	body	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`.
interface	body	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.
service_id	body	string	The UUID of the service to which the endpoint belongs.
region_id (Optional)	body	string	(Since v3.2) The ID of the region that contains the service endpoint.

Request Example¶

{
    "endpoint": {
        "interface": "public",
        "region_id": "RegionOne",
        "url": "http://example.com/identity/v3/endpoints/828384",
        "service_id": "9242e05f0c23467bbd1cf1f7a6e5e596"
    }
}

Response Parameters¶

Name	In	Type	Description
endpoint	body	object	An `endpoint` object.
links	body	object	The links for the `endpoint` resource.
url	body	string	The endpoint URL.
region	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
enabled	body	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	body	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.
service_id	body	string	The UUID of the service to which the endpoint belongs.
id	body	string	The endpoint ID.
region_id	body	string	(Since v3.2) The ID of the region that contains the service endpoint.

GET

/v3/endpoints/{endpoint_id}

Show endpoint details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/endpoints

Shows details for an endpoint.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
endpoint_id	path	string	The endpoint ID.

Response Parameters¶

Name	In	Type	Description
endpoint	body	object	An `endpoint` object.
name	body	string	The endpoint name.
links	body	object	The links for the `endpoint` resource.
url	body	string	The endpoint URL.
region	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
interface	body	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.
service_id	body	string	The UUID of the service to which the endpoint belongs.

Response Example¶

{
    "endpoint": {
        "enabled": true,
        "id": "01c3d5b92f7841ac83fb4b26173c12c7",
        "interface": "admin",
        "links": {
            "self": "http://example.com/identity/v3/endpoints/01c3d5b92f7841ac83fb4b26173c12c7"
        },
        "region": "RegionOne",
        "region_id": "RegionOne",
        "service_id": "3b2d6ad7e02c4cde8498a547601f1b8f",
        "url": "http://23.253.211.234:9696/"
    }
}

PATCH

/v3/endpoints/{endpoint_id}

Update endpoint

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/endpoint

Updates an endpoint.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
endpoint	body	object	An `endpoint` object.
url	body	string	The endpoint URL.
region	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
interface	body	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.
service_id	body	string	The UUID of the service to which the endpoint belongs.
endpoint_id	path	string	The endpoint ID.

Request Example¶

{
    "endpoint": {
        "interface": "public",
        "name": "Name",
        "region_id": "north",
        "url": "http://example.com/identity/v3/endpoints/828384",
        "service_id": "345678"
    }
}

Response Parameters¶

Name	In	Type	Description
endpoint	body	object	An `endpoint` object.
id	body	string	The endpoint ID.
links	body	object	The links for the `endpoint` resource.
url	body	string	The endpoint URL.
region	body	string	(Deprecated in v3.2) The geographic location of the service endpoint.
interface	body	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.
service_id	body	string	The UUID of the service to which the endpoint belongs.

Response Example¶

{
    "endpoint": {
        "id": "828384",
        "interface": "internal",
        "links": {
            "self": "http://example.com/identity/v3/endpoints/828384"
        },
        "region_id": "north",
        "service_id": "686766",
        "url": "http://example.com/identity/v3/endpoints/828384"
    }
}

DELETE

/v3/endpoints/{endpoint_id}

Delete endpoint

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/endpoint

Deletes an endpoint.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
endpoint_id	path	string	The endpoint ID.

Users¶

A user is an individual API consumer that is owned by a domain. A role explicitly associates a user with projects or domains. A user with no assigned roles has no access to OpenStack resources.

You can list, create, show details for, update, delete, and change the password for users.

You can also list groups, projects, and role assignments for a specified user. To list user roles, see Roles.

GET

/v3/users

List users

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/users

Lists users.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.

Request Parameters¶

Name	In	Type	Description
domain_id (Optional)	query	string	Filters the response by a domain ID.
enabled (Optional)	query	string	Filters the response by either enabled (`true`) or disabled (`false`) users.
idp_id (Optional)	query	string	Filters the response by an identity provider ID.
name (Optional)	query	string	Filters the response by a user name.
password_expires_at (Optional)	query	string	Filter results based on which user passwords have expired. The query should include an `operator` and a `timestamp` with a colon (`:`) separating the two, for example: password_expires_at={operator}:{timestamp} Valid operators are: `lt`, `lte`, `gt`, `gte`, `eq`, and `neq` lt: expiration time lower than the timestamp lte: expiration time lower than or equal to the timestamp gt: expiration time higher than the timestamp gte: expiration time higher than or equal to the timestamp eq: expiration time equal to the timestamp neq: expiration time not equal to the timestamp Valid timestamps are of the form: `YYYY-MM-DDTHH:mm:ssZ`. For example: /v3/users?password_expires_at=lt:2016-12-08T22:02:00Z The example would return a list of users whose password expired before the timestamp (`2016-12-08T22:02:00Z`).
protocol_id (Optional)	query	string	Filters the response by a protocol ID.
unique_id (Optional)	query	string	Filters the response by a unique ID.

Response Parameters¶

Name	In	Type	Description
links	body	object	The link to the collection of resources.
users	body	array	A list of `user` object, each containing:
default_project_id (Optional)	body	string	The ID of the default project for the user.
domain_id	body	string	The ID of the domain.
enabled	body	boolean	If the user is enabled, this value is `true`. If the user is disabled, this value is `false`.
id	body	string	The user ID.
links	body	object	The links for the `user` resource.
name	body	string	The user name. Must be unique within the owning domain.
password_expires_at	body	string	The date and time when the password expires. The time zone is UTC. This is a response object attribute; not valid for requests. A `null` value indicates that the password never expires. New in version 3.7

Response Example¶

{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/users"
    },
    "users": [
        {
            "domain_id": "default",
            "enabled": true,
            "id": "2844b2a08be147a08ef58317d6471f1f",
            "links": {
                "self": "http://example.com/identity/v3/users/2844b2a08be147a08ef58317d6471f1f"
            },
            "name": "glance",
            "password_expires_at": null
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "4ab84ab39de54f4d96eaff8f2145a7cd",
            "links": {
                "self": "http://example.com/identity/v3/users/4ab84ab39de54f4d96eaff8f2145a7cd"
            },
            "name": "swiftusertest1",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "56696a9a04864d63877a3d06a6f0b24b",
            "links": {
                "self": "http://example.com/identity/v3/users/56696a9a04864d63877a3d06a6f0b24b"
            },
            "name": "swift",
            "password_expires_at": null
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "5acb638d15da44fc8de41b9a4bd41875",
            "links": {
                "self": "http://example.com/identity/v3/users/5acb638d15da44fc8de41b9a4bd41875"
            },
            "name": "alt_demo",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "7596e862b1af473c8ed6ae99d35b51e3",
            "links": {
                "self": "http://example.com/identity/v3/users/7596e862b1af473c8ed6ae99d35b51e3"
            },
            "name": "demo",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "802edb2141b44e77bbde241417450749",
            "links": {
                "self": "http://example.com/identity/v3/users/802edb2141b44e77bbde241417450749"
            },
            "name": "nova",
            "password_expires_at": null
        },
        {
            "domain_id": "592ab0800d3745baaf45c610fa41950a",
            "enabled": true,
            "id": "9aca3883784647fe9aff3a50d922489a",
            "links": {
                "self": "http://example.com/identity/v3/users/9aca3883784647fe9aff3a50d922489a"
            },
            "name": "swiftusertest4",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "a1251b011f9345e68c2458b841152034",
            "links": {
                "self": "http://example.com/identity/v3/users/a1251b011f9345e68c2458b841152034"
            },
            "name": "swiftusertest3",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "a43f46eb318041f6b712143862e3ad70",
            "links": {
                "self": "http://example.com/identity/v3/users/a43f46eb318041f6b712143862e3ad70"
            },
            "name": "neutron",
            "password_expires_at": null
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "b964a9e51c0046a4a84d3f83a135a97c",
            "links": {
                "self": "http://example.com/identity/v3/users/b964a9e51c0046a4a84d3f83a135a97c"
            },
            "name": "admin",
            "password_expires_at": null
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "dc87e591c0d247d5ac04e873bd8a1646",
            "links": {
                "self": "http://example.com/identity/v3/users/dc87e591c0d247d5ac04e873bd8a1646"
            },
            "name": "cinder",
            "password_expires_at": null
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "ed214dc1c2c6468b926c96eca6c8aee9",
            "links": {
                "self": "http://example.com/identity/v3/users/ed214dc1c2c6468b926c96eca6c8aee9"
            },
            "name": "glance-swift",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        },
        {
            "domain_id": "default",
            "enabled": true,
            "id": "f4f6587b058a4f46a00242549b430d37",
            "links": {
                "self": "http://example.com/identity/v3/users/f4f6587b058a4f46a00242549b430d37"
            },
            "name": "swiftusertest2",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    ]
}

POST

/v3/users

Create user

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/users

Creates a user.

Response Codes¶

Success¶

Code	Reason
`201 - Created`	Resource was created and is ready to use.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
user	body	object	A `user` object, containing:
default_project_id (Optional)	body	string	The ID of the default project for the user. Setting this attribute does not grant any actual authorization on the project, and is merely provided for convenience. Therefore, the referenced project does not need to exist within the user domain. (Since v3.1) If the user does not have authorization to their default project, the default project is ignored at token creation. (Since v3.1) Additionally, if your default project is not valid, a token is issued without an explicit scope of authorization.
domain_id (Optional)	body	string	The ID of the domain for the user.
enabled (Optional)	body	boolean	If the user is enabled, this value is `true`. If the user is disabled, this value is `false`.
name	body	string	The user name. Must be unique within the owning domain.
password (Optional)	body	string	The password for the user.

Request Example¶

{
    "user": {
        "default_project_id": "263fd9",
        "domain_id": "1789d1",
        "enabled": true,
        "name": "James Doe",
        "password": "secretsecret"
    }
}

Response Parameters¶

Name	In	Type	Description
user	body	object	A `user` object, containing:
default_project_id (Optional)	body	string	The ID of the default project for the user.
domain_id	body	string	The ID of the domain.
enabled	body	boolean	If the user is enabled, this value is `true`. If the user is disabled, this value is `false`.
id	body	string	The user ID.
links	body	object	The links for the `user` resource.
name	body	string	The user name. Must be unique within the owning domain.
password_expires_at	body	string	The date and time when the password expires. The time zone is UTC. This is a response object attribute; not valid for requests. A `null` value indicates that the password never expires. New in version 3.7

GET

/v3/users/{user_id}

Show user details

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/user

Shows details for a user.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.

Response Parameters¶

Name	In	Type	Description
user	body	object	A `user` object, containing:
default_project_id (Optional)	body	string	The ID of the default project for the user.
domain_id	body	string	The ID of the domain.
enabled	body	boolean	If the user is enabled, this value is `true`. If the user is disabled, this value is `false`.
id	body	string	The user ID.
links	body	object	The links for the `user` resource.
name	body	string	The user name. Must be unique within the owning domain.
password_expires_at	body	string	The date and time when the password expires. The time zone is UTC. This is a response object attribute; not valid for requests. A `null` value indicates that the password never expires. New in version 3.7

Response Example¶

{
    "user": {
        "default_project_id": "263fd9",
        "domain_id": "1789d1",
        "enabled": true,
        "id": "9fe1d3",
        "links": {
            "self": "https://example.com/identity/v3/users/9fe1d3"
        },
        "name": "jsmith",
        "password_expires_at": "2016-11-06T15:32:17.000000"
    }
}

PATCH

/v3/users/{user_id}

Update user

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/user

Updates a user’s password, or whether they are enabled or disabled.

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

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.
`501 - Not Implemented`	The server either does not recognize the request method, or it lacks the ability to fulfill the request.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.
user	body	object	A `user` object, containing:
default_project_id (Optional)	body	string	The new ID of the default project for the user.
domain_id (Optional)	body	string	The ID of the new domain for the user. The ability to change the domain of a user is now deprecated, and will be removed in subequent release. It is already disabled by default in most Identity service implementations.
enabled (Optional)	body	boolean	Enables or disables the user. An enabled user can authenticate and receive authorization. A disabled user cannot authenticate or receive authorization. Additionally, all tokens that the user holds become no longer valid. If you reenable this user, pre-existing tokens do not become valid. To enable the user, set to `true`. To disable the user, set to `false`. Default is `true`.
name (Optional)	body	string	The new name for the user. Must be unique within the owning domain.
password (Optional)	body	string	The new password for the user.

Request Example¶

{
    "user": {
        "default_project_id": "263fd9",
        "enabled": true
    }
}

Response Parameters¶

Name	In	Type	Description
user	body	object	A `user` object, containing:
default_project_id (Optional)	body	string	The ID of the default project for the user.
domain_id	body	string	The ID of the domain.
enabled	body	boolean	If the user is enabled, this value is `true`. If the user is disabled, this value is `false`.
id	body	string	The user ID.
links	body	object	The links for the `user` resource.
name	body	string	The user name. Must be unique within the owning domain.
password_expires_at	body	string	The date and time when the password expires. The time zone is UTC. This is a response object attribute; not valid for requests. A `null` value indicates that the password never expires. New in version 3.7

Response Example¶

{
    "user": {
        "default_project_id": "263fd9",
        "domain_id": "1789d1",
        "enabled": true,
        "id": "ff4e51",
        "links": {
            "self": "https://example.com/identity/v3/users/ff4e51"
        },
        "name": "jamesdoe",
        "password_expires_at": "2016-11-06T15:32:17.000000"
    }
}

DELETE

/v3/users/{user_id}

Delete user

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/user

Deletes a user.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.

GET

/v3/users/{user_id}/groups

List groups to which a user belongs

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/user_groups

Lists groups to which a user belongs.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.

Response Example¶

{
    "groups": [
        {
            "description": "Developers cleared for work on all general projects",
            "domain_id": "1789d1",
            "id": "ea167b",
            "links": {
                "self": "https://example.com/identity/v3/groups/ea167b"
            },
            "name": "Developers"
        },
        {
            "description": "Developers cleared for work on secret projects",
            "domain_id": "1789d1",
            "id": "a62db1",
            "links": {
                "self": "https://example.com/identity/v3/groups/a62db1"
            },
            "name": "Secure Developers"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/users/9fe1d3/groups",
        "previous": null,
        "next": null
    }
}

GET

/v3/users/{user_id}/projects

List projects for user

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/user_projects

List projects for a user.

Response Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.

Response Example¶

{
    "projects": [
        {
            "description": "description of this project",
            "domain_id": "161718",
            "enabled": true,
            "id": "456788",
            "links": {
                "self": "http://example.com/identity/v3/projects/456788"
            },
            "name": "a project name",
            "parent_id": "212223"
        },
        {
            "description": "description of this project",
            "domain_id": "161718",
            "enabled": true,
            "id": "456789",
            "links": {
                "self": "http://example.com/identity/v3/projects/456789"
            },
            "name": "another domain",
            "parent_id": "212223"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/users/313233/projects",
        "previous": null,
        "next": null
    }
}

POST

/v3/users/{user_id}/password

Change password for user

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/user_change_password

Changes the password for a user.

Note

This API call does not require a token for authentication.

Response Codes¶

Success¶

Code	Reason
`204 - No Content`	The server has fulfilled the request.

Error¶

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Request Parameters¶

Name	In	Type	Description
user_id	path	string	The user ID.
user	body	object	A `user` object, containing:
original_password	body	string	The original password for the user.
password	body	string	The new password for the user.

Request Example¶

{
    "user": {
        "password": "new_secretsecret",
        "original_password": "secretsecret"
    }
}

updated: 'Fri Jun 16 10:33:24 2017, commit 45265c0'

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.