Cloud-A OpenStack API Documentation

Gets an authentication token that permits access to the OpenStack services REST API.

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

GET

List versions

Lists information about all Identity API versions.

Normal response codes

200

Error response codes

Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)

Example Responses

{
    "versions": {
        "values": [
            {
                "id": "v3.4",
                "links": [
                    {
                        "href": "https://keystone.ca-ns-1.clouda.ca:8443/v3/",
                        "rel": "self"
                    }
                ],
                "media-types": [
                    {
                        "base": "application/json",
                        "type": "application/vnd.openstack.identity-v3+json"
                    }
                ],
                "status": "stable",
                "updated": "2015-03-30T00:00:00Z"
            },
            {
                "id": "v2.0",
                "links": [
                    {
                        "href": "https://keystone.ca-ns-1.clouda.ca:8443/v2.0/",
                        "rel": "self"
                    },
                    {
                        "href": "http://docs.openstack.org/",
                        "rel": "describedby",
                        "type": "text/html"
                    }
                ],
                "media-types": [
                    {
                        "base": "application/json",
                        "type": "application/vnd.openstack.identity-v2.0+json"
                    }
                ],
                "status": "stable",
                "updated": "2014-04-17T00:00:00Z"
            }
        ]
    }
}

This operation does not accept a request body.

GET

/v3

Show API version details

Shows details for the Identity API v3.

Normal response codes

200

Error response codes

Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404),

Response parameters

Parameter	Style	Type	Description
version	plain	xsd:string	A `version` object.
status	plain	xsd:string	The status of the version. For example, `experimental` or `stable`.
updated	plain	xsd:string	The date and time stamp for the last update.
media-types	plain	xsd:string	A `media-types` object, which shows the supported media types.
id	plain	xsd:string	The version ID, such as `v3.0`.
links	plain	xsd:string	The version links.

Example Responses

{
    "version": {
        "id": "v3.4",
        "links": [
            {
                "href": "https://keystone.ca-ns-1.clouda.ca:8443/v3/",
                "rel": "self"
            }
        ],
        "media-types": [
            {
                "base": "application/json",
                "type": "application/vnd.openstack.identity-v3+json"
            }
        ],
        "status": "stable",
        "updated": "2015-03-30T00:00:00Z"
    }
}

This operation does not accept a request body.

Manages tokens.

POST

/v3/auth/tokens

Authenticate

Authenticates and generates a token.

Each REST request against the Identity Service requires the X-Auth-Token header. Clients obtain this token and the URL endpoints for other service APIs by supplying their valid credentials to the authentication service.

A REST interface provides client authentication by using the POST method with auth/tokens the path. The body of the request must include a payload of credentials including the authentication method and, optionally, the authorization scope. The scope includes either a project or domain. If you include both project and domain, this call returns the HTTP Bad Request (400) status code because a token cannot be simultaneously scoped as both a project and domain.

If you do not include the optional scope and the authenticating user has a defined default project (the default_project_id attribute for the user), that default project is treated as the preferred authorization scope.

If no default project is defined, the token is issued without an explicit scope of authorization.

Provide one of the following sets of credentials to authenticate: User ID and password, user name and password scoped by domain ID or name, user ID and password scoped by project ID or name with or without domain scope, an OTP token and auth code, or token.

The following examples demonstrate authentication requests with different types of credentials.

If scope is included, project id uniquely identifies the project. However, project name uniquely identifies the project only when used in conjunction with a domain ID or a domain name.

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

If the subject token has expired, this call returns the HTTP 404 status code.

The Identity API treats expired tokens as not valid tokens.

The deployment determines how long expired tokens are stored.

As the following example responses show, the response to an authentication request returns the token ID in the X-Subject-Token header instead of in the token data.

If the call has no explicit authorization scope, the response does not contain the catalog, project, domain, or roles fields. However, the response still uniquely identifies the user.

A token scoped to a project also has both a service catalog and the user's roles applicable to the project.

A token scoped to a domain also has both a service catalog and the user's roles applicable to the project.

Optionally, The Identity API implementation might return an authentication attribute to indicate the supported authentication methods.

For authentication processes that require multiple round trips, The Identity API implementation might return an HTTP 401 Unauthorized error with additional information for the next authentication step.

For users with 2FA / OTP enabled on their accounts, a token will be returned via the password method that must be used with the totp auth method to exchange for a full token. OTP Scoped tokens cannot be used for anything other than exchanging.

The following examples illustrate several possible HTTP 401 Unauthorized authentication errors. Other errors like HTTP 403 Forbidden are also possible.

Normal response codes

201

Error response codes

Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)

Request parameters

Parameter	Style	Type	Description
auth	plain	xsd:string	An `auth` object.
identity	plain	xsd:string	An `identity` object.
methods	plain	xsd:string	The authentication method, which is `password` or `token`. With password authentication, you can specify user ID and password, user name and password scoped by domain ID or name, or user ID and password scoped by project ID or name with or without domain scope. With otp authentication, you pass the token for exchange, and the TOTP auth code or recovery code. With token authentication, you specify the token ID.
password (Optional)	plain	xsd:string	A `password` object.
scope (Optional)	plain	xsd:string	Token can be scoped for a domain or project. Specify either an `id` or `name` to uniquely identify the domain or project. Use project `name` only in conjunction with a domain `id` or `name`.
token (Optional)	plain	xsd:string	A `token` object. With token authentication, the `id` uniquely identifies the token. This method is typically used in combination with a request to change authorization scope.
user (Optional)	plain	xsd:string	A `user` object. Specify `id` or `name` to uniquely identify the user and `password`. Use `name` only in conjunction with a domain `id` or `name`.
id (Optional)	plain	xsd:string	With password authentication, `id` uniquely identifies the user. However, `name` uniquely identifies the user when used in conjunction with a domain `id` or `name`.
name (Optional)	plain	xsd:string	The user name.
password (Optional)	plain	xsd:string	The password.
token_exchange (Optional)	plain	xsd:string	A token for a user who has OTP enabled, and has been scoped as being OTP only. This will return after any password method login for OTP enabled users.
auth_code (Optional)	plain	xsd:string	The Time-based OTP auth code generated by an application that knows your OTP seed (usually a mobile app such as FreeOTP, or Google Authenticator).

Example Requests

Authenticate with domain ID, user name, and password request

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "domain": {
                        "id": "default"
                    },
                    "name": "joe@example.com",
                    "password": "secretsecret"
                }
            }
        }
    }
}

Authenticate with user name, password, and project ID scope request

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "domain": {
                        "id": "default"
                    },
                    "name": "joe@example.com",
                    "password": "secretsecret"
                }
            }
        },
        "scope": {
            "project": {
                "id": "263fd9"
            }
        }
    }
}

Authenticate by Exchanging an OTP Scoped token, and an auth code for a usable token request

{
    "auth": {
        "identity": {
            "methods": [
                "totp"
            ],
            "totp": {
                "token_exchange": "otp-scoped-token-id",
                "auth_code": "123456"
            }
        }
    }
}

Authenticate with token request

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "e80b74"
            }
        }
    }
}

Example Responses

Authenticate without scope response

{
    "token": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "issued_at": "2013-02-27T16:30:59.999999Z",
        "methods": [
            "password"
        ],
        "user": {
            "domain": {
                "id": "1789d1",
                "links": {
                    "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/domains/1789d1"
                },
                "name": "example.com"
            },
            "id": "0ca8f6",
            "links": {
                "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/users/0ca8f6"
            },
            "name": "Joe"
        }
    }
}

Authenticate with OTP enabled response

{
    "token": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "issued_at": "2013-02-27T16:30:59.999999Z",
        "methods": [
            "password"
        ],
        "OS-OTP": {
            "otp_seed_id": "f4256ba"
        },
        "endpoints": [ ... ],
        "project": { ... },
        "roles": [ ... ],
        "user": {
            "domain": { ... },
            "id": "0ca8f6",
            "links": {
                "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/users/0ca8f6"
            },
            "name": "joe@example.com"
        }
    }
}

Authenticate with project scope response

{
    "token": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "issued_at": "2013-02-27T16:30:59.999999Z",
        "methods": [
            "password"
        ],
        "endpoints": [
                {
                    "links": {
                        "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/endpoints/130_P"
                    },
                    "id": "example-a",
                    "interface": "public",
                    "region_id": "regionOne",
                    "url": "https://keystone.ca-ns-1.clouda.ca:8443/v2.0/",
                    "service_id": "100"
                },
                {
                    "links": {
                        "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/endpoints/example-a"
                    },
                    "id": "example-a",
                    "interface": "public",
                    "region_id": "regionOne",
                    "url": "https://keystone.ca-ns-1.clouda.ca:8443/v3/",
                    "service_id": "100"
                }
        ],
        "project": {
            "domain": {
                "id": "1789d1",
                "links": {
                    "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/domains/1789d1"
                },
                "name": "example.com"
            },
            "id": "263fd9",
            "links": {
                "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/projects/263fd9"
            },
            "name": "project-x"
        },
        "roles": [
            {
                "id": "76e72a",
                "links": {
                    "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/roles/76e72a"
                },
                "name": "admin"
            },
            {
                "id": "f4f392",
                "links": {
                    "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/roles/f4f392"
                },
                "name": "member"
            }
        ],
        "user": {
            "domain": {
                "id": "1789d1",
                "links": {
                    "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/domains/1789d1"
                },
                "name": "example.com"
            },
            "id": "0ca8f6",
            "links": {
                "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/users/0ca8f6"
            },
            "name": "joe@example.com"
        }
    }
}

Error: Basic HTTP 401 Not Authorized Response

{
    "error": {
        "code": 401,
        "message": "The request you have made requires authentication",
        "title": "Not Authorized"
    }
}

Error: HTTP 401 Not Authorized with Supported Methods Response

{
    "error": {
        "code": 401,
        "identity": {
            "methods": [
                "password",
                "token",
                "challenge-response"
            ]
        },
        "message": "Need to authenticate with one or more supported methods",
        "title": "Not Authorized"
    }
}

Manages the catalog of services.

GET

/v3/services

List services

Lists services.

Normal response codes

200

Error response codes

Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)

Request parameters

Parameter	Style	Type	Description
X-Auth-Token	header	xsd:string	A valid authentication token for an administrative user.
type (Optional)	query	xsd:string	Filters by service type. Service types include compute, ec2, image, and identity.
page (Optional)	query	xsd:string	Enables you to page through the list.
per_page (Optional)	query	xsd:string	Sets the page size for paging through the list. Default page size is 30.

Response parameters

Parameter	Style	Type	Description
services	plain	xsd:string	A `services` object.
description (Optional)	plain	xsd:string	The description.
enabled	plain	xsd:boolean	If `true`, the service is enabled. If `false`, the service is disabled.
id	plain	xsd:string	The service ID.
links	plain	xsd:string	The service links.
name	plain	xsd:string	The service name.
type	plain	xsd:string	The service type.

Example Responses

{
    "links": {
        "next": null,
        "previous": null,
        "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/services"
    },
    "services": [
        {
            "description": "Keystone Identity Service",
            "enabled": true,
            "id": "686766",
            "links": {
                "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/services/686766"
            },
            "name": "keystone",
            "type": "identity"
        },
        {
            "enabled": true,
            "id": "936521",
            "links": {
                "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/services/936521"
            },
            "type": "volume"
        }
    ]
}

GET

/v3/services/{service_id}

Show service details

Shows details for a specified service.

Normal response codes

200

Error response codes

Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)

Request parameters

Parameter	Style	Type	Description
X-Auth-Token	header	xsd:string	A valid authentication token for an administrative user.
service_id	URI	capi:uuid	The service ID.

Response parameters

Parameter	Style	Type	Description
service	plain	xsd:string	A `service` object.
description (Optional)	plain	xsd:string	The description.
enabled	plain	xsd:boolean	If `true`, the service is enabled. If `false`, the service is disabled.
id	plain	xsd:string	The service ID.
links	plain	xsd:string	The service links.
name	plain	xsd:string	The service name.
type	plain	xsd:string	The service type.

Example Responses

{
    "service": {
        "description": "Keystone Identity Service",
        "enabled": true,
        "id": "686766",
        "links": {
            "self": "https://keystone.ca-ns-1.clouda.ca:8443/v3/services/686766"
        },
        "name": "keystone",
        "type": "identity"
    }
}

This operation does not accept a request body.

API Reference

Identity API v3

API versions

Example Responses

Response parameters

Example Responses

Tokens

Request parameters

Example Requests

Example Responses

Service catalog

Request parameters

Response parameters

Example Responses

Request parameters

Response parameters

Example Responses