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.

Note that the V3 API implements HEAD for all GET requests. Each HEAD request contains the same headers and HTTP status code as the corresponding GET API.

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.14 (Ussuri)

  • New attribute authorization_ttl for identity providers

  • New attribute membership_expires_at when listing groups for a user

  • Ability to persist group memberships carried through mapping for a federated user

  • Added the ability to create, update and delete federated attributes for a user

What’s New in Version 3.13 (Train)

  • New parameter access_rules for application credentials

  • New read-only API /v3/users/{user_id}/access_rules for viewing access rules

What’s New in Version 3.12 (Stein)

  • New optional multi-factor auth process involving auth receipts

What’s New in Version 3.11 (Rocky)

  • New endpoint /v3/limits-model for discovering the limit model in effect

  • New description field in registered and project limits

  • New project_id filters for project limits

  • New parameter include_limits for project detail query

What’s New in Version 3.10 (Queens)

  • Introduction of the Application Credentials API.

  • Introduction of an experimental Unified Limits API.

  • Ability to grant system role assignments and obtain system-scoped tokens.

What’s New in Version 3.9 (Queens)

  • Addition of tags attribute to project.

  • New APIs to interact with the tags attribute.

What’s New in Version 3.8 (Ocata)

  • 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 (Newton)

  • 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 (Mitaka)

  • 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 (Liberty)

  • 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 (Kilo)

  • 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 (Juno)

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 (Icehouse)

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 (Havana)

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 (Grizzly)

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

Relationships

The entries within the operations below contain a relationship link, which appears as a valid URI, however these are actually URN (Uniform Resource Name), which are similar to GUID except it uses a URI syntax so that it is easier to be read. These links do not resolve to anything valid, but exist to show a relationship.

Identity API Operations

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

Authentication and token management

The Identity service generates tokens in exchange for authentication credentials. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project, domain, or the deployment system.

The body of an authentication request must include a payload that specifies the authentication methods, which are normally just password or token, the credentials, and, optionally, the authorization scope. You can scope a token to a project, domain, the deployment system, or the token can be unscoped. You cannot scope a token to multiple scope targets.

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

In the case of multi-factor authentication (MFA) more than one authentication method needs to be supplied to authenticate. As of v3.12 a failure due to MFA rules only partially being met will result in an auth receipt ID being returned in the response header Openstack-Auth-Receipt, and a response body that details the receipt itself and the missing authentication methods. Supplying the auth receipt ID in the Openstack-Auth-Receipt header in a follow-up authentication request, with the missing authentication methods, will result in a valid token by reusing the successful methods from the first request. This allows MFA authentication to be a multi-step process.

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.

Alternatively, in v3.10 the Identity API service introduced the concept of system role assignments and system-scoped tokens. APIs that affect the deployment system require system-scoped tokens.

The Identity API considers expired tokens as invalid, which is determined by the deployment’s configuration.

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.

  • Not all MFA rules were satisfied.

  • The specified Openstack-Auth-Receipt header is not valid.

Forbidden (403)

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

Not Found (404)

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

Conflict (409)

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

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

POST
/v3/auth/tokens

Password authentication with unscoped authorization

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

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

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

Request

Parameters

Name

In

Type

Description

nocatalog (Optional)

query

string

(Since v3.1) nocatalog only works for scoped token. For unscoped token, the authentication response always excludes the service catalog.

domain

body

object

A domain object

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.

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

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.

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.

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

Example
{
    "token": {
        "methods": [
            "password"
        ],
        "expires_at": "2015-11-06T15:32:17.893769Z",
        "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

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

The request body must include a payload that specifies the password authentication method which includes the credentials in addition to a project, domain, or system authorization scope.

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

Request

Parameters

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 the system (Since v3.10), a project, or a domain (Since v3.4). If multiple scopes are specified in the same request (e.g. project and domain or domain and system) an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to multiple authorization targets. 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.

System-Scoped Example
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "system": {
                "all": true
            }
        }
    }
}
Domain-Scoped with Domain ID Example
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "domain": {
                "id": "default"
            }
        }
    }
}
Domain-Scoped with Domain Name Example
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "domain": {
                "name": "Default"
            }
        }
    }
}
Project-Scoped with Project ID Example
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "project": {
                "id": "a6944d763bf64ee6a275f1263fae0352"
            }
        }
    }
}
Project-Scoped with Project Name Example
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "password": "devstacker"
                }
            }
        },
        "scope": {
            "project": {
                "domain": {
                    "id": "default"
                },
                "name": "admin"
            }
        }
    }
}

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.

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

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.

system (Optional)

body

object

A system object containing information about which parts of the system the token is scoped to. If the token is scoped to the entire deployment system, the system object will consist of {"all": true}. This is only included in tokens that are scoped to the system.

domain (Optional)

body

object

A domain object including the id and name representing the domain the token is scoped to. This is only included in tokens that are scoped to a domain.

project (Optional)

body

object

A project object including the id, name and domain object representing the project the token is scoped to. This is only included in tokens that are scoped to a project.

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.

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.

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

System-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "system": {
            "all": true
        },
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
Domain-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "domain": {
            "id": "default",
            "name": "Default"
        },
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
Project-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "is_domain": false,
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password"
        ],
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "a6944d763bf64ee6a275f1263fae0352",
            "name": "admin"
        },
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
POST
/v3/auth/tokens

Password authentication with explicit unscoped authorization

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

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

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

Request

Parameters

Name

In

Type

Description

nocatalog (Optional)

query

string

(Since v3.1) nocatalog only works for scoped token. For unscoped token, the authentication response always excludes 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 user has authorization to their 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.

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

methods

body

array

The authentication method. For password authentication, specify password.

roles

body

array

A list of role objects

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.

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.

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

404 - Not Found

The requested resource could not be found.

Example
{
    "token": {
        "methods": [
            "password"
        ],
        "expires_at": "2015-11-09T01:42:57.527363Z",
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": null
        },
        "audit_ids": [
            "lC2Wj1jbQe-dLjLyOx4qPQ"
        ],
        "issued_at": "2015-11-09T00:42:57.527404Z"
    }
}
POST
/v3/auth/tokens

Token authentication with unscoped authorization

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

In the request body, provide the token ID.

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

Request

Parameters

Name

In

Type

Description

nocatalog (Optional)

query

string

(Since v3.1) nocatalog only works for scoped token. For unscoped token, the authentication response always excludes 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.

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.

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

Example
{
    "token": {
        "methods": [
            "token"
        ],
        "expires_at": "2015-11-05T22:00:11.000000Z",
        "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"
    }
}
POST
/v3/auth/tokens

Token authentication with scoped authorization

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

The request body must include a payload that specifies the token authentication method which includes the token in addition to a project, domain, or system authorization scope.

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

Request

Parameters

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 the system (Since v3.10), a project, or a domain (Since v3.4). If multiple scopes are specified in the same request (e.g. project and domain or domain and system) an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to multiple authorization targets. 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.

System-Scoped Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "system": {
                "all": true
            }
        }
    }
}
Domain-Scoped with Domain ID Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "domain": {
                "id": "default"
            }
        }
    }
}
Domain-Scoped with Domain Name Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "domain": {
                "name": "Default"
            }
        }
    }
}
Project-Scoped with Project ID Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "project": {
                "id": "a6944d763bf64ee6a275f1263fae0352"
            }
        }
    }
}
Project-Scoped with Project Name Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "'$OS_TOKEN'"
            }
        },
        "scope": {
            "project": {
                "domain": {
                    "id": "default"
                },
                "name": "admin"
            }
        }
    }
}

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.

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

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.

system (Optional)

body

object

A system object containing information about which parts of the system the token is scoped to. If the token is scoped to the entire deployment system, the system object will consist of {"all": true}. This is only included in tokens that are scoped to the system.

domain (Optional)

body

object

A domain object including the id and name representing the domain the token is scoped to. This is only included in tokens that are scoped to a domain.

project (Optional)

body

object

A project object including the id, name and domain object representing the project the token is scoped to. This is only included in tokens that are scoped to a project.

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.

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.

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

System-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw",
            "oppr9r6pQo6mWb5Ji4zgwg"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "token",
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "system": {
            "all": true
        },
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
Domain-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw",
            "oppr9r6pQo6mWb5Ji4zgwg"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "domain": {
            "id": "default",
            "name": "Default"
        },
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "token",
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
Project-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw",
            "oppr9r6pQo6mWb5Ji4zgwg"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "is_domain": false,
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "token",
            "password"
        ],
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "a6944d763bf64ee6a275f1263fae0352",
            "name": "admin"
        },
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
POST
/v3/auth/tokens

Token authentication with explicit unscoped authorization

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.

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

Request

Parameters

Name

In

Type

Description

nocatalog (Optional)

query

string

(Since v3.1) nocatalog only works for scoped token. For unscoped token, the authentication response always excludes 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 user has authorization to their 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.

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.

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

404 - Not Found

The requested resource could not be found.

Example
{
    "token": {
        "methods": [
            "token"
        ],
        "expires_at": "2015-11-05T22:00:11.000000Z",
        "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"
    }
}
POST
/v3/auth/tokens

Multi-Step authentication (2-Factor Password and TOTP example)

Authenticates an identity and generates a token. Uses the password authentication method, then the totp method, with an auth receipt in between.

This assumes that MFA has been enabled for the user, and a rule has been defined requiring authentication with both password and totp.

The first request body must at least include a payload that specifies one of password or totp authentication methods which includes the credentials in addition to an optional scope. If only one method is supplied then an auth receipt will be returned. Scope is not retained in the receipt and must be resupplied in subsequent requests.

While it is very possible to supply all the required auth methods at once, this example shows the multi-step process which is likely to be more common.

More than 2 factors can be used but the same process applies to those as well; either all auth methods are supplied at once, or in steps with one or more auth receipts in between.

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

First Request

Parameters

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 the system (Since v3.10), a project, or a domain (Since v3.4). If multiple scopes are specified in the same request (e.g. project and domain or domain and system) an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to multiple authorization targets. 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.

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

Response

Here we are expecting a 401 status, and a returned auth receipt.

Parameters

Name

In

Type

Description

Openstack-Auth-Receipt

header

string

The auth receipt. A partially successful authentication response returns the auth receipt ID in this header rather than in the response body.

methods

body

array

The authentication methods, which are commonly password, totp, or other methods. Indicates the accumulated set of authentication methods that were used to obtain the receipt. For example, if the receipt was obtained by password authentication, it contains password. Later, if the receipt is exchanged by using another authentication method one or more times, the subsequently created receipts could contain both password and totp in their methods attribute.

expires_at

body

string

The date and time when the receipt 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 receipt never expires.

issued_at

body

string

The date and time when the receipt 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.

user

body

object

A user object.

required_auth_methods

body

list of lists

A list of authentication rules that may be used with the auth receipt to complete the authentication process.

Status Code
Success

Code

Reason

401 - Unauthorized

User has successfully supplied some auth methods, but not enough for full authentication.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Authentication attempt has failed.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Auth Receipt Example
{
    "receipt":{
        "expires_at":"2018-07-05T08:39:23.000000Z",
        "issued_at":"2018-07-05T08:34:23.000000Z",
        "methods": [
            "password"
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin"
        }
    },
    "required_auth_methods": [
        ["totp", "password"]
    ]
}

Second Request

Parameters

Name

In

Type

Description

Openstack-Auth-Receipt

header

string

The auth receipt. A partially successful authentication response returns the auth receipt 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.

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 the system (Since v3.10), a project, or a domain (Since v3.4). If multiple scopes are specified in the same request (e.g. project and domain or domain and system) an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to multiple authorization targets. 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.

totp

body

object

The totp 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 totp authentication, specify totp.

Example
{
    "auth": {
        "identity": {
            "methods": [
                "totp"
            ],
            "totp": {
                "user": {
                    "id": "ee4dfb6e5540447cb3741905149d9b6e",
                    "passcode": "123456"
                }
            }
        },
        "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.

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

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.

system (Optional)

body

object

A system object containing information about which parts of the system the token is scoped to. If the token is scoped to the entire deployment system, the system object will consist of {"all": true}. This is only included in tokens that are scoped to the system.

domain (Optional)

body

object

A domain object including the id and name representing the domain the token is scoped to. This is only included in tokens that are scoped to a domain.

project (Optional)

body

object

A project object including the id, name and domain object representing the project the token is scoped to. This is only included in tokens that are scoped to a project.

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.

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.

Status 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

Authentication attempt has failed. Either the auth receipt has expired, or the additional auth methods supplied were invalid.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Project-Scoped Password and TOTP Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "is_domain": false,
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password",
            "totp"
        ],
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "a6944d763bf64ee6a275f1263fae0352",
            "name": "admin"
        },
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
GET
/v3/auth/tokens

Validate and show information for token

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

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

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

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

Request

Parameters

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.

methods

body

array

The authentication methods, which are commonly password, token, or other 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.

catalog (Optional)

body

array

A catalog object.

system (Optional)

body

object

A system object containing information about which parts of the system the token is scoped to. If the token is scoped to the entire deployment system, the system object will consist of {"all": true}. This is only included in tokens that are scoped to the system.

domain (Optional)

body

object

A domain object including the id and name representing the domain the token is scoped to. This is only included in tokens that are scoped to a domain.

project (Optional)

body

object

A project object including the id, name and domain object representing the project the token is scoped to. This is only included in tokens that are scoped to a project.

roles

body

array

A list of role objects

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.

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

Unscoped Example
{
    "token": {
        "audit_ids": [
            "mAjXQhiYRyKwkB4qygdLVg"
        ],
        "expires_at": "2015-11-05T22:00:11.000000Z",
        "issued_at": "2015-11-05T21:00:33.819948Z",
        "methods": [
            "password"
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "10a2e6e717a245d9acad3e5f97aeca3d",
            "name": "admin",
            "password_expires_at": null
        }
    }
}
System-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "system": {
            "all": true
        },
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
Domain-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "domain": {
            "id": "default",
            "name": "Default"
        },
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password"
        ],
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
Project-Scoped Example
{
    "token": {
        "audit_ids": [
            "3T2dc1CGQxyJsHdDu1xkcw"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "068d1b359ee84b438266cb736d81de97",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "8bfc846841ab441ca38471be6d164ced",
                        "interface": "admin",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "beb6d358c3654b4bada04d4663b640b9",
                        "interface": "internal",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "type": "identity",
                "id": "050726f278654128aba89757ae25950c",
                "name": "keystone"
            }
        ],
        "expires_at": "2015-11-07T02:58:43.578887Z",
        "is_domain": false,
        "issued_at": "2015-11-07T01:58:43.578929Z",
        "methods": [
            "password"
        ],
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "a6944d763bf64ee6a275f1263fae0352",
            "name": "admin"
        },
        "roles": [
            {
                "id": "51cc68287d524c759f47c811e6463340",
                "name": "admin"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "ee4dfb6e5540447cb3741905149d9b6e",
            "name": "admin",
            "password_expires_at": "2016-11-06T15:32:17.000000"
        }
    }
}
HEAD
/v3/auth/tokens

Check token

Validates a token.

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

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

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

Request

Parameters

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.

Response

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

DELETE
/v3/auth/tokens

Revoke token

Revokes a token.

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

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

Request

Parameters

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.

Response

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

GET
/v3/auth/catalog

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

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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:5000"
                }
            ],
            "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

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.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

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.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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
    }
}
GET
/v3/auth/system

Get available system scopes

New in version 3.10

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

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

Request

Parameters

Name

In

Type

Description

X-Auth-Token

header

string

A valid authentication token for an administrative user.

Response

Parameters

Name

In

Type

Description

links

body

object

The links to the domain resource.

system

body

array

A list of systems to access based on role assignments.

Status Codes
Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

400 - Bad Request

Some content in the request was invalid.

Example
{
    "system": [
        {
            "all": true
        }
    ],
    "links": {
        "self": "https://example.com/identity/v3/auth/system"
    }
}

Application Credentials

Application credentials provide a way to delegate a user’s authorization to an application without sharing the user’s password authentication. This is a useful security measure, especially for situations where the user’s identification is provided by an external source, such as LDAP or a single-sign-on service. Instead of storing user passwords in config files, a user creates an application credential for a specific project, with all or a subset of the role assignments they have on that project, and then stores the application credential identifier and secret in the config file.

Multiple application credentials may be active at once, so you can easily rotate application credentials by creating a second one, converting your applications to use it one by one, and finally deleting the first one.

Application credentials are limited by the lifespan of the user that created them. If the user is deleted, disabled, or loses a role assignment on a project, the application credential is deleted.

Application credentials can have their privileges limited in two ways. First, the owner may specify a subset of their own roles that the application credential may assume when getting a token for a project. For example, if a user has the member role on a project, they also have the implied role reader and can grant the application credential only the reader role for the project:

"roles": [
    {"name": "reader"}
]

Users also have the option of delegating more fine-grained access control to their application credentials by using access rules. For example, to create an application credential that is constricted to creating servers in nova, the user can add the following access rules:

"access_rules": [
    {
        "path": "/v2.1/servers",
        "method": "POST",
        "service": "compute"
    }
]

The "path" attribute of application credential access rules uses a wildcard syntax to make it more flexible. For example, to create an application credential that is constricted to listing server IP addresses, you could use either of the following access rules:

"access_rules": [
    {
        "path": "/v2.1/servers/*/ips",
        "method": "GET",
        "service": "compute"
    }
]

or equivalently:

"access_rules": [
    {
        "path": "/v2.1/servers/{server_id}/ips",
        "method": "GET",
        "service": "compute"
    }
]

In both cases, a request path containing any server ID will match the access rule. For even more flexibility, the recursive wildcard ** indicates that request paths containing any number of / will be matched. For example:

"access_rules": [
    {
        "path": "/v2.1/**",
        "method": "GET",
        "service": "compute"
    }
]

will match any nova API for version 2.1.

An access rule created for one application credential can be re-used by providing its ID to another application credential, for example:

"access_rules": [
    {
        "id": "abcdef"
    }
]
POST
/v3/auth/tokens

Authenticating with an Application Credential

To authenticate with an application credential, specify “application_credential” as the auth method. You are not allowed to request a scope, as the scope is retrieved from the application credential.

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

Request

Parameters

Name

In

Type

Description

identity

body

object

An identity object.

methods

body

array

The authentication method. To authenticate with an application credential, specify application_credential.

application_credential

body

object

An application credential object.

id (Optional)

body

string

The ID of the application credential used for authentication. If not provided, the application credential must be identified by its name and its owning user.

name (Optional)

body

string

The name of the application credential used for authentication. If provided, must be accompanied by a user object.

secret

body

string

The secret for authenticating the application credential.

user (Optional)

body

object

A user object, required if an application credential is identified by name and not ID.

Example

An application credential can be identified by an ID:

{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "id": "423f19a4ac1e4f48bbb4180756e6eb6c",
                "secret": "rEaqvJka48mpv"
            }
        }
    }
}

It can also be identified by its name and a user object:

{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "name": "monitoring",
                "secret": "rEaqvJka48mpv",
                "user": {
                    "id": "423f19a4ac1e4f48bbb4180756e6eb6c"
                }
            }
        }
    }
}

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.

token

body

object

A token object.

application_credential

body

object

Whether the application credential is permitted to be used for creating and deleting additional application credentials and trusts.

application_credential.id

body

string

The ID of the application credential.

application_credential.name

body

string

The name of the application credential.

application_credential.restricted

body

boolean

A flag indicating whether the application credential may be used for creation or destruction of other application credentials or trusts.

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.

catalog

body

array

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

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.

methods

body

array

The authentication methods, which are commonly password, token, or other 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.

project

body

object

A project object

roles

body

array

A list of role objects

user

body

object

A user object.

user.id (Optional)

body

string

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

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

Example
{
    "token": {
        "application_credential": {
          "id": "423f19a4ac1e4f48bbb4180756e6eb6c",
          "name": "monitoring",
          "restricted": true
        },
        "audit_ids": [
            "9JsolhssRzKfyayTIiCRUg"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity",
                        "region": "RegionOne",
                        "interface": "admin",
                        "id": "81737f23cd8f45169fcd700cb658c8ad"
                    },
                    {
                        "region_id": "RegionOne",
                        "url": "http://example.com/identity",
                        "region": "RegionOne",
                        "interface": "public",
                        "id": "a7b9155184ed4607853304408e7e8d32"
                    }
                ],
                "type": "identity",
                "id": "408af8b8554248fc8d686bef54ae3bf6",
                "name": "keystone"
            }
        ],
        "expires_at": "2018-01-15T22:14:05.000000Z",
        "is_domain": false,
        "issued_at": "2018-01-15T21:14:05.000000Z",
        "methods": [
            "application_credential"
        ],
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "231c62fb0fbd485b995e8b060c3f0d98",
            "name": "demo"
        },
        "roles": [
            {
                "id": "df8b7e3bf6fb49e9ba19122da2bae916",
                "name": "Member"
            }
        ],
        "user": {
            "password_expires_at": null,
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "fd786d56402c4d1691372e7dee0d00b5",
            "name": "demo"
        }
    }
}

A token created with an application credential will have the scope and roles designated by the application credential.

POST
/v3/users/{user_id}/application_credentials

Create application credential

Creates an application credential for a user on the project to which the current token is scoped.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the application credential.

application_credential

body

object

An application credential object.

name

body

string

The name of the application credential. Must be unique to a user.

secret (Optional)

body

string

The secret that the application credential will be created with. If not provided, one will be generated.

description (Optional)

body

string

A description of the application credential’s purpose.

expires_at (Optional)

body

string

An optional expiry time for the application credential. If unset, the application credential does not expire.

roles (Optional)

body

array

An optional list of role objects, identified by ID or name. The list may only contain roles that the user has assigned on the project. If not provided, the roles assigned to the application credential will be the same as the roles in the current token.

unrestricted (Optional)

body

boolean

An optional flag to restrict whether the application credential may be used for the creation or destruction of other application credentials or trusts. Defaults to false.

access_rules (Optional)

body

list

A list of access_rules objects

Example
{
    "application_credential": {
        "name": "monitoring",
        "secret": "rEaqvJka48mpv",
        "description": "Application credential for monitoring.",
        "expires_at": "2018-02-27T18:30:59Z",
        "roles": [
            {"name": "Reader"}
        ],
        "access_rules": [
            {
                "path": "/v2.0/metrics",
                "method": "GET",
                "service": "monitoring"
            }
        ],
        "unrestricted": false
    }
}

Response

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.

409 - Conflict

This operation conflicted with another operation on this resource.

Parameters

Name

In

Type

Description

application_credential

body

object

The application credential object.

id

body

string

The ID of the application credential.

name

body

string

The name of the application credential.

secret

body

string

The secret for the application credential, either generated by the server or provided by the user. This is only ever shown once in the response to a create request. It is not stored nor ever shown again. If the secret is lost, a new application credential must be created.

description

body

string

A description of the application credential’s purpose.

expires_at

body

string

The expiration time of the application credential, if one was specified.

project_id

body

string

The ID of the project the application credential was created for and that authentication requests using this application credential will be scoped to.

roles

body

array

A list of one or more roles that this application credential has associated with its project. A token using this application credential will have these same roles.

access_rules

body

list

A list of access_rules objects

unrestricted

body

boolean

A flag indicating whether the application credential may be used for creation or destruction of other application credentials or trusts.

links

body

object

The link to the resources in question.

Example
{
  "application_credential": {
    "description": "Application credential for monitoring.",
    "roles": [
      {
        "id": "6aff702516544aeca22817fd3bc39683",
        "domain_id": null,
        "name": "Reader"
      }
    ],
    "access_rules": [
      {
        "path": "/v2.0/metrics",
        "id": "07d719df00f349ef8de77d542edf010c",
        "service": "monitoring",
        "method": "GET"
      }
    ],
    "links": {
      "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
    },
    "expires_at": "2018-02-27T18:30:59.000000",
    "unrestricted": false,
    "secret": "rEaqvJka48mpv",
    "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
    "id": "58d61ff8e6e34accb35874016d1dba8b",
    "name": "monitoring"
  }
}
GET
/v3/users/{user_id}/application_credentials

List application credentials

List all application credentials for a user.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the application credential.

name (Optional)

query

string

The name of the application credential. Must be unique to a user.

Response

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

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.

Parameters

Name

In

Type

Description

application_credential

body

object

The application credential object.

id

body

string

The ID of the application credential.

name

body

string

The name of the application credential.

description

body

string

A description of the application credential’s purpose.

expires_at

body

string

The expiration time of the application credential, if one was specified.

project_id

body

string

The ID of the project the application credential was created for and that authentication requests using this application credential will be scoped to.

roles

body

array

A list of one or more roles that this application credential has associated with its project. A token using this application credential will have these same roles.

access_rules

body

list

A list of access_rules objects

unrestricted

body

boolean

A flag indicating whether the application credential may be used for creation or destruction of other application credentials or trusts.

links

body

object

The link to the collection of resources.

Example
{
    "links": {
        "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials",
        "previous": null,
        "next": null
    },
    "application_credentials": [
        {
            "description": "Application credential for backups.",
            "roles": [
                {
                    "domain_id": null,
                    "name": "Writer",
                    "id": "6aff702516544aeca22817fd3bc39683"
                }
            ],
            "access_rules": [
            ],
            "links": {
                "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/308a7e905eee4071aac5971744c061f6"
            },
            "expires_at": "2018-02-27T18:30:59.000000",
            "unrestricted": false,
            "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
            "id": "308a7e905eee4071aac5971744c061f6",
            "name": "backups"
        },
        {
            "description": "Application credential for monitoring.",
            "roles": [
                {
                    "id": "6aff702516544aeca22817fd3bc39683",
                    "domain_id": null,
                    "name": "Reader"
                }
            ],
            "access_rules": [
              {
                "path": "/v2.0/metrics",
                "id": "07d719df00f349ef8de77d542edf010c",
                "service": "monitoring",
                "method": "GET"
              }
            ],
            "links": {
                "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
            },
            "expires_at": "2018-02-27T18:30:59.000000",
            "unrestricted": false,
            "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
            "id": "58d61ff8e6e34accb35874016d1dba8b",
            "name": "monitoring"
        }
    ]
}
GET
/v3/users/{user_id}/application_credentials/{application_credential_id}

Show application credential details

Show details of an application credential.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the application credential.

application_credential_id

path

string

The ID of the application credential.

Response

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

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.

Parameters

Name

In

Type

Description

application_credential

body

object

The application credential object.

id

body

string

The ID of the application credential.

name

body

string

The name of the application credential.

description

body

string

A description of the application credential’s purpose.

expires_at

body

string

The expiration time of the application credential, if one was specified.

project_id

body

string

The ID of the project the application credential was created for and that authentication requests using this application credential will be scoped to.

roles

body

array

A list of one or more roles that this application credential has associated with its project. A token using this application credential will have these same roles.

access_rules

body

list

A list of access_rules objects

unrestricted

body

boolean

A flag indicating whether the application credential may be used for creation or destruction of other application credentials or trusts.

links

body

object

The link to the resources in question.

Example
{
  "application_credential": {
    "description": "Application credential for monitoring.",
    "roles": [
      {
        "id": "6aff702516544aeca22817fd3bc39683",
        "domain_id": null,
        "name": "Reader"
      }
    ],
    "access_rules": [
      {
        "path": "/v2.0/metrics",
        "id": "07d719df00f349ef8de77d542edf010c",
        "service": "monitoring",
        "method": "GET"
      }
    ],
    "links": {
      "self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
    },
    "expires_at": "2018-02-27T18:30:59.000000",
    "unrestricted": false,
    "project_id": "231c62fb0fbd485b995e8b060c3f0d98",
    "id": "58d61ff8e6e34accb35874016d1dba8b",
    "name": "monitoring"
  }
}
DELETE
/v3/users/{user_id}/application_credentials/{application_credential_id}

Delete application credential

Delete an application credential.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the application credential.

application_credential_id

path

string

The ID of the application credential.

Response

Success

Code

Reason

204 - No Content

The server has fulfilled the request.

Error

Code

Reason

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.

GET
/v3/users/{user_id}/access_rules

List access rules

List all access rules for a user.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the access rule.

Response

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

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.

Parameters

Name

In

Type

Description

access_rules

body

list

A list of access_rules objects

id

body

string

The ID of the access rule

path

body

string

The API path that the application credential is permitted to access. May use named wildcards such as {tag} or the unnamed wildcard * to match against any string in the path up to a /, or the recursive wildcard ** to include / in the matched path.

method

body

string

The request method that the application credential is permitted to use for a given API endpoint.

service

body

string

The service type identifier for the service that the application credential is permitted to access. Must be a service type that is listed in the service catalog and not a code name for a service.

links

body

object

The link to the collection of resources.

Example
{
  "links": {
    "self": "https://example.com/identity/v3/users/3e0716aefcad4b129a0f19f95ec9489e/access_rules",
    "previous": null,
    "next": null
  },
  "access_rules": [
    {
      "path": "/v2.0/metrics",
      "links": {
        "self": "https://example.com/identity/v3/access_rules/07d719df00f349ef8de77d542edf010c"
      },
      "id": "07d719df00f349ef8de77d542edf010c",
      "service": "monitoring",
      "method": "GET"
    }
  ]
}
GET
/v3/users/{user_id}/access_rules/{access_rule_id}

Show access rule details

Show details of an access rule.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the access rule.

access_rule_id

path

string

The ID of the access rule.

Response

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

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.

Parameters

Name

In

Type

Description

access_rules

body

list

A list of access_rules objects

id

body

string

The ID of the access rule

path

body

string

The API path that the application credential is permitted to access. May use named wildcards such as {tag} or the unnamed wildcard * to match against any string in the path up to a /, or the recursive wildcard ** to include / in the matched path.

method

body

string

The request method that the application credential is permitted to use for a given API endpoint.

service

body

string

The service type identifier for the service that the application credential is permitted to access. Must be a service type that is listed in the service catalog and not a code name for a service.

links

body

object

The link to the collection of resources.

Example
{
  "access_rule": {
    "path": "/v2.0/metrics",
    "links": {
      "self": "https://example.com/identity/v3/access_rules/07d719df00f349ef8de77d542edf010c"
    },
    "id": "07d719df00f349ef8de77d542edf010c",
    "service": "monitoring",
    "method": "GET"
  }
}
DELETE
/v3/users/{user_id}/access_rules/{access_rule_id}

Delete access rule

Delete an access rule. An access rule that is still in use by an application credential cannot be deleted.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The ID of the user who owns the access rule.

access_rule_id

path

string

The ID of the access rule.

Response

Success

Code

Reason

204 - No Content

The server has fulfilled the request.

Error

Code

Reason

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.

Credentials

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

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

POST
/v3/credentials

Create credential

Creates a credential.

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

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

Request

Parameters

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

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.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Shows details for a credential.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Updates a credential.

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

Request

Parameters

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Deletes a credential.

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

Request

Parameters

Name

In

Type

Description

credential_id

path

string

The UUID for the credential.

Response

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Lists all domains.

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

Request

Parameters

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.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request

Response

Parameters

Name

In

Type

Description

domains

body

array

A list of domain objects

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Creates a domain.

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

Request

Parameters

Name

In

Type

Description

domain

body

object

A domain object

explicit_domain_id (Optional)

body

string

The ID of the domain. A domain created this way will not use an auto-generated ID, but will use the ID passed in instead. Identifiers passed in this way must conform to the existing ID generation scheme: UUID4 without dashes.

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.

options (Optional)

body

object

The resource options for the domain. Available resource options are immutable.

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

Response

Parameters

Name

In

Type

Description

domain

body

object

A domain object

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.

options

body

object

The resource options for the role. Available resource options are immutable.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

GET
/v3/domains/{domain_id}

Show domain details

Shows details for a domain.

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

Response

Parameters

Name

In

Type

Description

domain

body

object

A domain object

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.

options

body

object

The resource options for the role. Available resource options are immutable.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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",
        "options": {}
    }
}
PATCH
/v3/domains/{domain_id}

Update domain

Updates a domain.

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

domain

body

object

A domain object

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 invalid. However, if you reenable the domain, these tokens become valid again, providing that they haven’t expired.

description (Optional)

body

string

The new description of the domain.

name (Optional)

body

string

The new name of the domain.

options (Optional)

body

object

The resource options for the domain. Available resource options are immutable.

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

Response

Parameters

Name

In

Type

Description

domain

body

object

A domain object

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.

options

body

object

The resource options for the role. Available resource options are immutable.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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",
        "options": {}
    }
}
DELETE
/v3/domains/{domain_id}

Delete domain

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

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

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

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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.

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.

The API supports only the identity and ldap groups.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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.

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.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Example
{
    "driver": "ldap"
}
GET
/v3/domains/{domain_id}/config/{group}/{option}

Show domain group option configuration

Shows details for a domain group option configuration.

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

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Example
{
    "url": "http://myldap/root"
}
PATCH
/v3/domains/{domain_id}/config/{group}/{option}

Update domain group option configuration

Updates a domain group option configuration.

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

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

Request

Parameters

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.

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Example
{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "http://myldap/my_other_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
DELETE
/v3/domains/{domain_id}/config/{group}/{option}

Delete domain group option configuration

Deletes a domain group option configuration.

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

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

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

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Show domain group configuration

Shows details for a domain group configuration.

The API supports only the identity and ldap groups.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

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.

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

Request

Parameters

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Example
{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "http://myldap/my_new_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
DELETE
/v3/domains/{domain_id}/config/{group}

Delete domain group configuration

Deletes a domain group configuration.

The API supports only the identity and ldap groups.

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

group

path

string

The group ID.

Response

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

PUT
/v3/domains/{domain_id}/config

Create domain configuration

Creates a domain configuration.

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

Request

Parameters

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.

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.

Status Codes
Success

Code

Reason

200 - OK

Request was successful.

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.

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Shows details for a domain configuration.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Example
{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "http://myldap/root",
            "user_tree_dn": "ou=Users,dc=root,dc=org"
        }
    }
}
PATCH
/v3/domains/{domain_id}/config

Update domain configuration

Updates a domain configuration.

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

Request

Parameters

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Example
{
    "config": {
        "identity": {
            "driver": "ldap"
        },
        "ldap": {
            "url": "http://myldap/my_new_root",
            "user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
        }
    }
}
DELETE
/v3/domains/{domain_id}/config

Delete domain configuration

Deletes a domain configuration.

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

Response

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Lists groups.

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

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

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.

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

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

Creates a group.

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

Request

Parameters

Name

In

Type

Description

group

body

object

A group object

description (Optional)

body

string

The description of the group.

domain_id (Optional)

body

string

The ID of the domain of the group. If the domain ID is not provided in the request, the Identity service will attempt to pull the domain ID from the token used in the request. Note that this requires the use of a domain-scoped token.

name

body

string

The name of the group.

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

Response

Parameters

Name

In

Type

Description

group

body

object

A group object

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.

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

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

Shows details for a group.

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

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

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.

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

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

Updates a group.

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

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

Request

Parameters

Name

In

Type

Description

group_id

path

string

The group ID.

group

body

object

A group object

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.

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

Response

Parameters

Name

In

Type

Description

group

body

object

A group object

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.

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

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

Deletes a group.

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

Request

Parameters

Name

In

Type

Description

group_id

path

string

The group ID.

Response

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

GET
/v3/groups/{group_id}/users

List users in group

Lists the users that belong to a group.

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

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

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

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

Adds a user to a group.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The user ID.

group_id

path

string

The group ID.

Response

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

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

Check whether user belongs to group

Validates that a user belongs to a group.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The user ID.

group_id

path

string

The group ID.

Response

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

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

Remove user from group

Removes a user from a group.

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

Request

Parameters

Name

In

Type

Description

user_id

path

string

The user ID.

group_id

path

string

The group ID.

Response

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

OS-INHERIT

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

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.

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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.

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

List user’s inherited project roles on a domain

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

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

user_id

path

string

The user ID.

Response

Status Codes
Success

Code

Reason

200 - OK

Request was successful.

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

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

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

group_id

path

string

The group ID.

Response

Status Codes
Success

Code

Reason

200 - OK

Request was successful.

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

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

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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

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

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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

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

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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.

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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.

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

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

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

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

Request

Parameters

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.

Response

Status Codes
Success

Code

Reason

204 - No Content

The server has fulfilled the request.

GET
/v3/role_assignments

List role assignments

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

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

Request

Parameters

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.

Response

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

OS-PKI (DEPRECATED)

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

List revoked tokens

Lists revoked PKI tokens.

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

Response

Status Codes
Error

Code

Reason

410 - Gone

The access request to the target resource is no longer available.

Policies

Warning

The policies API is deprecated. Keystone is not a policy management service. Do not use this.

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

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

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

Create policy

Creates a policy.

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

Request

Parameters

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

GET
/v3/policies

List policies

Lists policies.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Shows details for a policy.

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

Request

Parameters

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Updates a policy.

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

Request

Parameters

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.

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Deletes a policy.

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

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

Response

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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. Creating a project without using a domain scoped token, i.e. using a project scoped token or a system scoped token, and also without specifying a domain or domain_id, the project will automatically be created on the default domain.

GET
/v3/projects

List projects

Lists projects.

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

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

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request

Response

Parameters

Name

In

Type

Description

links

body

object

The link to the collection of resources.

projects

body

array

A list of project objects

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

tags

body

array

A list of simple strings assigned to a project.

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

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,
            "tags": []
        },
        {
            "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,
            "tags": []
        },
        {
            "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,
            "tags": []
        },
        {
            "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,
            "tags": []
        },
        {
            "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,
            "tags": []
        },
        {
            "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,
            "tags": []
        },
        {
            "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,
            "tags": []
        },
        {
            "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,
            "tags": []
        }
    ]
}
POST
/v3/projects

Create project

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

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

Request

Parameters

Name

In

Type

Description

project

body

object

A project object

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.

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.

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

tags (Optional)

body

array

A list of simple strings assigned to a project. Tags can be used to classify projects into groups.

options (Optional)

body

object

The resource options for the project. Available resource options are immutable.

Examples

Sample for creating a regular project:

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

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

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

options

body

object

The resource options for the project. Available resource options are immutable.

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

GET
/v3/projects/{project_id}

Show project details

Shows details for a project.

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

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

include_limits (Optional)

query

key-only, no value expected

It should be used together with parents_as_list or subtree_as_list filter to add the related project’s limits into the response body.

Response

Parameters

Name

In

Type

Description

project

body

object

A project object

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

options

body

object

The resource options for the project. Available resource options are immutable.

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

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",
        "options": {}
    }
}
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",
        "options": {},
        "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
                }
            }
        ]
    }
}
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",
        "options": {},
        "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

Updates a project.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

project

body

object

A project object

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.

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.

tags (Optional)

body

array

A list of simple strings assigned to a project. Tags can be used to classify projects into groups.

options (Optional)

body

object

The resource options for the project. Available resource options are immutable.

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

Response

Parameters

Name

In

Type

Description

project

body

object

A project object

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

options

body

object

The resource options for the project. Available resource options are immutable.

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

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,
        "tags": [],
        "options": {}
    }
}
DELETE
/v3/projects/{project_id}

Delete project

Deletes a project.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

Response

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

Project tags

Projects within keystone can be tagged with one to many simple strings. Tags for projects follow the guidelines for resource tags set by the API Working Group.

Tags for projects have the following restrictions:

Note

  • Tags are case sensitive

  • Forward Slash ‘/’ is not allowed to be in a tag name

  • Commas ‘,’ are not allowed to be in a tag name in order to simplify requests that specify lists of tags

  • Each project can have a maximum of 80 tags

  • Each tag can be a maximum of 255 characters in length

Warning

We discourage the use of project tags for sensitive information like billing or account codes. By default, access to project tags isn’t exclusive to system administrators or users. Domain and project administrators are allowed to tag projects they have authorization to access. Domain and project users (e.g., users with the member or reader roles) can view all project tags on all projects within their domain or on projects they are authorized to access.

GET
/v3/projects/{project_id}/tags

List tags for a project

Lists all tags within a project.

Note

HEAD can be used here as well

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

Response

Parameters

Name

In

Type

Description

tags

body

array

A list of simple strings assigned to a project.

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

Example
{
    "tags": ["foo", "bar"]
}
PUT
/v3/projects/{project_id}/tags

Modify tag list for a project

Modifies the tags for a project. Any existing tags not specified will be deleted.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

tags

body

array

A list of simple strings assigned to a project.

Example
{
    "tags": ["foo", "bar"]
}

Response

Parameters

Name

In

Type

Description

tags

body

array

A list of simple strings assigned to a project.

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

Example
{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://identity:5000/v3/projects"
    },
    "projects": [
        {
            "description": "Test Project",
            "domain_id": "default",
            "enabled": true,
            "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
            "links": {
                "self": "http://identity:5000/v3/projects/3d4c2c82bd5948f0bcab0cf3a7c9b48c"
            },
            "name": "demo",
            "tags": ["foo", "bar"]
        }
    ]
}
DELETE
/v3/projects/{project_id}/tags

Remove all tags from a project

Remove all tags from a given project.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

Response

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

GET
/v3/projects/{project_id}/tags/{tag}

Check if project contains tag

Checks if a project contains the specified tag.

Note

HEAD can be used here as well

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

tag

path

string

A simple string associated with a project. Can be used for assigning values to projects and filtering based on those values.

Response

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

PUT
/v3/projects/{project_id}/tags/{tag}

Add single tag to a project

Creates the specified tag and adds it to the list of tags in the project.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

tag

path

string

A simple string associated with a project. Can be used for assigning values to projects and filtering based on those values.

Response

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

DELETE
/v3/projects/{project_id}/tags/{tag}

Delete single tag from project

Remove a single tag from a project.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

tag

path

string

A simple string associated with a project. Can be used for assigning values to projects and filtering based on those values.

Response

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

Filtering and searching by tags

Projects can be searched or filtered by tags. The following table and examples define how to filter projects by tags. Filters can also be combined for more complex searching.

Tag Query

Description

tags

Projects that contain all of the specified tags

tags-any

Projects that contain at least one of the specified tags

not-tags

Projects that do not contain exactly all of the specified tags

not-tags-any

Projects that do not contain any one of the specified tags

To request the list of projects that have a single tag, the tags query parameter should be set to the desired tag name. The following example returns projects with the “foo” tag:

GET /v3/projects?tags=foo

To request the list of projects that have two or more tags, the tags argument should be set to the list of tags, separated by commas. In this situation, the tags given must all be present for a project to be included in the query result. The following example returns projects that have the “foo” and “bar” tags:

GET /v3/projects?tags=foo,bar

To request the list of projects that have at least one tag from a given list, the tags-any argument should be set to the list of tags, separated by commas. In this situation as long as one of the given tags is present, the project will be included in the query result. The following example returns projects that have the “foo” OR “bar” tag:

GET /v3/projects?tags-any=foo,bar

To request the list of projects that do not have a list of tags, the not-tags argument should be set to the list of tags, separated by commas. In this situation, the tags given must all be absent for a project to be included in the query result. The following example returns projects that do not have the “foo” nor the “bar” tag:

GET /v3/projects?not-tags=foo,bar

To request the list of projects that do not have at least one of a list of tags, the not-tags-any argument should be set to the list of tags, separated by commas. In this situation, as long as one of the given tags is absent, the project will be included in the query result. Example The following example returns projects that do not have the “foo” tag or do not have the “bar” tag:

GET /v3/projects?not-tags-any=foo,bar

The tags, tags-any, not-tags and not-tags-any arguments can be combined to build more complex queries. The following example returns projects that have the “foo” and “bar” tags, plus at least one of “red” and “blue”:

GET /v3/projects?tags=foo,bar&tags-any=red,blue

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

Shows details for a region, by ID.

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

Request

Parameters

Name

In

Type

Description

region_id

path

string

The region ID.

Response

Parameters

Name

In

Type

Description

region

body

object

A region object

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

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.

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

Request

Parameters

Name

In

Type

Description

region_id

path

string

The region ID.

region

body

object

A region object

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.

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

Response

Parameters

Name

In

Type

Description

region

body

object

A region object

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

Deletes a region.

The following error might occur:

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

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

Request

Parameters

Name

In

Type

Description

region_id

path

string

The region ID.

Response

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

GET
/v3/regions

List regions

Lists regions.

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

Request

Parameters

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

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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

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.

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

Request

Parameters

Name

In

Type

Description

region

body

object

A region object

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.

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

Response

Parameters

Name

In

Type

Description

region

body

object

A region object

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.

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

405 - Method Not Allowed

Method is not valid for this endpoint.

409 - Conflict

This operation conflicted with another operation on this resource.

413 - Request Entity Too Large

The request is larger than the server is willing or able to process.

415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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 the system, or 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}
    
  • List system role assignments for a specific user:

    GET /role_assignments?scope.system=all?user.id={user_id}
    
  • List system role assignments for all users and groups:

    GET /role_assignments?scope.system=all
    

Since Identity API v3.10, you can grant role assignments to users and groups on an entity called the system. The role assignment API also supports listing and filtering role assignments on the system.

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, domain, or the entire system. 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

Lists roles.

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

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

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.

description

body

string

The role description.

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

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"
            },
            "description": "My new role",
            "name": "admin"
        },
        {
            "id": "642bcfc75c384fd181adf34d9b2df897",
            "links": {
                "self": "http://example.com/identity/v3/roles/642bcfc75c384fd181adf34d9b2df897"
            },
            "description": "My new role",
            "name": "anotherrole"
        },
        {
            "id": "779a76d74f544224a7ef8762ca0de627",
            "links": {
                "self": "http://example.com/identity/v3/roles/779a76d74f544224a7ef8762ca0de627"
            },
            "description": "My new role",
            "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"
            },
            "description": "My new role",
            "name": "ResellerAdmin"
        },
        {
            "id": "f127b97616f24d3ebceb7be840210adc",
            "links": {
                "self": "http://example.com/identity/v3/roles/f127b97616f24d3ebceb7be840210adc"
            },
            "description": null,
            "name": "service"
        }
    ]
}
POST
/v3/roles

Create role

Creates a role.

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

Request

Parameters

Name

In

Type

Description

role

body

object

A role object

name

body

string

The role name.

domain_id (Optional)

body

string

The ID of the domain of the role.

description (Optional)

body

string

Add description about the role.

options (Optional)

body

object

The resource options for the role. Available resource options are immutable.

Example
{
    "role": {
        "description": "My new role",
        "name": "developer"
    }
}
Example for Domain Specific Role
{
    "role": {
        "description": "My new role"
        "domain_id": "92e782c4988642d783a95f4a87c3fdd7",
        "name": "developer"
    }
}

Response

Parameters

Name

In

Type

Description

role

body

object

A role object

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.

description

body

string

The role description.

options

body

object

The resource options for the role. Available resource options are immutable.

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

GET
/v3/roles/{role_id}

Show role details

Shows details for a role.

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

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

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.

description

body

string

The role description.

options

body

object

The resource options for the role. Available resource options are immutable.

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

Example
{
    "role": {
        "domain_id": "d07792fd66ac4ed881723ab9f1c9925f",
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "description": "My new role",
        "name": "Developer",
        "options": {}
    }
}
PATCH
/v3/roles/{role_id}

Update role

Updates a role.

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

Request

Parameters

Name

In

Type

Description

role_id

path

string

The role ID.

role

body

object

A role object

name (Optional)

body

string

The new role name.

description (Optional)

body

string

The new role description.

options (Optional)

body

object

The resource options for the role. Available resource options are immutable.

Example
{
    "role": {
        "description": "My new role",
        "name": "Developer"
    }
}

Response

Parameters

Name

In

Type

Description

role

body

object

A role object

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.

description

body

string

The role description.

options

body

object

The resource options for the role. Available resource options are immutable.

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

Example
{
    "role": {
        "domain_id": "73748865fb964ded9e836d491d32dcfb",
        "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
        "links": {
            "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
        },
        "description": "My new role",
        "name": "Developer",
        "options": {}
    }
}
DELETE
/v3/roles/{role_id}

Delete role

Deletes a role.

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

Request

Parameters

Name

In

Type

Description

role_id

path

string

The role ID.

Response

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

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

List role assignments for group on domain

Lists role assignments for a group on a domain.

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

Request

Parameters

Name

In

Type

Description

domain_id

path

string

The domain ID.

group_id

path

string

The group ID.

Response

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

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

Assigns a role to a group on a domain.

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

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.

Response

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

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

Check whether group has role assignment on domain

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

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

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.

Response

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

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

Unassign role from group on domain

Unassigns a role from a group on a domain.

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

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.

Response

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

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

List role assignments for user on domain

Lists role assignments for a user on a domain.

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

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

id

body

string

The role ID.

links

body

object

The link to the resources in question.

name

body

string

The role name.

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

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

Assigns a role to a user on a domain.

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

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.

Response

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

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

Check whether user has role assignment on domain

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

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

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.

Response

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

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

Unassigns role from user on domain

Unassigns a role from a user on a domain.

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

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.

Response

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

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

List role assignments for group on project

Lists role assignments for a group on a project.

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

Request

Parameters

Name

In

Type

Description

project_id

path

string

The project ID.

group_id

path

string

The group ID.

Response

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

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

Assigns a role to a group on a project.

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

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.

Response

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

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

Check whether group has role assignment on project

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

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

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.

Response

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

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

Unassign role from group on project

Unassigns a role from a group on a project.

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

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.

Response

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

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

List role assignments for user on project