Identity API v2.0 (DEPRECATED)

Extensions

GET
/v2.0/extensions/{alias}
Show extension details

Shows details for an extension, by alias.

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

Request

Name In Type Description
alias body string The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”

Response Parameters

Name In Type Description
x-openstack-request-id (Optional) header string A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.
alias body string The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”
updated body string The date and time stamp when the extension was last updated.
description body string The description of the tenant. If not set, this value is null.
name body string Endpoint name.

Response Example

{
    "extension": {
        "updated": "2013-07-07T12:00:0-00:00",
        "name": "OpenStack OAUTH1 API",
        "links": [
            {
                "href": "https://github.com/openstack/identity-api",
                "type": "text/html",
                "rel": "describedby"
            }
        ],
        "namespace": "http://docs.openstack.org/identity/api/ext/OS-OAUTH1/v1.0",
        "alias": "OS-OAUTH1",
        "description": "OpenStack OAuth 1.0a Delegated Auth Mechanism."
    }
}
GET
/v2.0/extensions
List extensions

Lists available extensions.

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

Response Parameters

Name In Type Description
x-openstack-request-id (Optional) header string A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.
alias body string The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”
updated body string The date and time stamp when the extension was last updated.
description body string The description of the tenant. If not set, this value is null.
name body string Endpoint name.

Response Example

{
    "extensions": {
        "values": [
            {
                "updated": "2013-07-07T12:00:0-00:00",
                "name": "OpenStack S3 API",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/s3tokens/v1.0",
                "alias": "s3tokens",
                "description": "OpenStack S3 API."
            },
            {
                "updated": "2013-07-23T12:00:0-00:00",
                "name": "OpenStack Keystone Endpoint Filter API",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api/blob/master/openstack-identity-api/v3/src/markdown/identity-api-v3-os-ep-filter-ext.md",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-EP-FILTER/v1.0",
                "alias": "OS-EP-FILTER",
                "description": "OpenStack Keystone Endpoint Filter API."
            },
            {
                "updated": "2014-02-24T20:51:0-00:00",
                "name": "OpenStack Revoke API",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api/blob/master/openstack-identity-api/v3/src/markdown/identity-api-v3-os-revoke-ext.md",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-REVOKE/v1.0",
                "alias": "OS-REVOKE",
                "description": "OpenStack revoked token reporting mechanism."
            },
            {
                "updated": "2013-12-17T12:00:0-00:00",
                "name": "OpenStack Federation APIs",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-FEDERATION/v1.0",
                "alias": "OS-FEDERATION",
                "description": "OpenStack Identity Providers Mechanism."
            },
            {
                "updated": "2013-07-11T17:14:00-00:00",
                "name": "OpenStack Keystone Admin",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0",
                "alias": "OS-KSADM",
                "description": "OpenStack extensions to Keystone v2.0 API enabling Administrative Operations."
            },
            {
                "updated": "2014-01-20T12:00:0-00:00",
                "name": "OpenStack Simple Certificate API",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-SIMPLE-CERT/v1.0",
                "alias": "OS-SIMPLE-CERT",
                "description": "OpenStack simple certificate retrieval extension"
            },
            {
                "updated": "2013-07-07T12:00:0-00:00",
                "name": "OpenStack OAUTH1 API",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-OAUTH1/v1.0",
                "alias": "OS-OAUTH1",
                "description": "OpenStack OAuth 1.0a Delegated Auth Mechanism."
            },
            {
                "updated": "2013-07-07T12:00:0-00:00",
                "name": "OpenStack EC2 API",
                "links": [
                    {
                        "href": "https://github.com/openstack/identity-api",
                        "type": "text/html",
                        "rel": "describedby"
                    }
                ],
                "namespace": "http://docs.openstack.org/identity/api/ext/OS-EC2/v1.0",
                "alias": "OS-EC2",
                "description": "OpenStack EC2 Credentials backend."
            }
        ]
    }
}

Tokens and tenants

GET
/v2.0/tenants
List tenants

Lists tenants to which the token has access.

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

Response Parameters

Name In Type Description
description body string The description of the tenant. If not set, this value is null.
tenants_links body array Links of the tenants.
enabled body boolean Indicates whether the tenant is enabled or disabled.
tenants body array One or more tenant Objects.
id (Optional) body string The token ID. This field is required in the token object.
name body string Endpoint name.

Response Example

{
    "tenants": [
        {
            "id": "1234",
            "name": "ACME Corp",
            "description": "A description ...",
            "enabled": true
        },
        {
            "id": "3456",
            "name": "Iron Works",
            "description": "A description ...",
            "enabled": true
        }
    ],
    "tenants_links": []
}
POST
/v2.0/tokens
Authenticate

Authenticates and generates a token.

The Identity API is a RESTful web service. It is the entry point to all service APIs. To access the Identity API, you must know its URL.

Each REST request against Identity requires the X-Auth-Token header. Clients obtain this token, along with the URL to other service APIs, by first authenticating against Identity with valid credentials.

To authenticate, you must provide either a user ID and password or a token.

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

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

The Identity API treats expired tokens as no longer valid tokens.

The deployment determines how long expired tokens are stored.

To view the trust object, you need to set trust enable on the keystone configuration.

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

Request

Name In Type Description
username (Optional) body string The user name. Required if you include the passwordCredentials object. Otherwise, you must provide a token.
passwordCredentials (Optional) body string A passwordCredentials object. To authenticate, you must provide either a user ID and password or a token.
tenantId (Optional) body string The tenant ID. Both the tenantId and tenantName attributes are optional and mutually exclusive. If you specify both attributes, the server returns the Bad Request (400) response code.
token (Optional) body object A token object. Required if you do not provide a password credential.
tenantName (Optional) body string The tenant name. Both the tenantId and tenantName attributes are optional and mutually exclusive. If you specify both attributes, the server returns the Bad Request (400) response code.
password (Optional) body string The password of the user. Required if you include the passwordCredentials object. Otherwise, you must provide a token.
id (Optional) body string The token ID. This field is required in the token object.

Request Example

{
    "auth": {
        "tenantName": "demo",
        "token": {
            "id": "cbc36478b0bd8e67e89469c7749d4127"
        }
    }
}

Response Parameters

Name In Type Description
impersonation (Optional) body boolean The impersonation flag.
endpoints_links body array Links for the endpoint.
serviceCatalog body array List of serviceCatalog objects.
description body string The description of the tenant. If not set, this value is null.
type body string Endpoint type.
expires body string

The date and time when the token expires.

The date and time stamp format is ISO 8601:

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

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

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

A null value indicates that the token never expires.

enabled body boolean Indicates whether the tenant is enabled or disabled.
name body string Endpoint name.
access body object An access object.
trustee_user_id (Optional) body string The trustee user ID.
token (Optional) body object A token object. Required if you do not provide a password credential.
user body object A user object, which shows the username, roles_links, id, roles, and name.
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±hh:mm

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

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

trustor_user_id (Optional) body string The trustor user ID.
endpoints body array One or more endpoints objects. Each object shows the adminURL, region, internalURL, id, and publicURL for the endpoint.
trust (Optional) body object A trust object.
id (Optional) body string The token ID. This field is required in the token object.
tenant body object A tenant object.
metadata body object A metadata object.

Response Example

{
    "access": {
        "token": {
            "issued_at": "2014-01-30T15:30:58.819584",
            "expires": "2014-01-31T15:30:58Z",
            "id": "aaaaa-bbbbb-ccccc-dddd",
            "tenant": {
                "description": null,
                "enabled": true,
                "id": "fc394f2ab2df4114bde39905f800dc57",
                "name": "demo"
            }
        },
        "serviceCatalog": [
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57",
                        "id": "2dad48f09e2a447a9bf852bcd93548ef",
                        "publicURL": "http://23.253.72.207:8774/v2/fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "compute",
                "name": "nova"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:9696/",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:9696/",
                        "id": "97c526db8d7a4c88bbb8d68db1bdcdb8",
                        "publicURL": "http://23.253.72.207:9696/"
                    }
                ],
                "endpoints_links": [],
                "type": "network",
                "name": "neutron"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57",
                        "id": "93f86dfcbba143a39a33d0c2cd424870",
                        "publicURL": "http://23.253.72.207:8776/v2/fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "volumev2",
                "name": "cinder"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8774/v3",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8774/v3",
                        "id": "3eb274b12b1d47b2abc536038d87339e",
                        "publicURL": "http://23.253.72.207:8774/v3"
                    }
                ],
                "endpoints_links": [],
                "type": "computev3",
                "name": "nova"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:3333",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:3333",
                        "id": "957f1e54afc64d33a62099faa5e980a2",
                        "publicURL": "http://23.253.72.207:3333"
                    }
                ],
                "endpoints_links": [],
                "type": "s3",
                "name": "s3"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:9292",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:9292",
                        "id": "27d5749f36864c7d96bebf84a5ec9767",
                        "publicURL": "http://23.253.72.207:9292"
                    }
                ],
                "endpoints_links": [],
                "type": "image",
                "name": "glance"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57",
                        "id": "37c83a2157f944f1972e74658aa0b139",
                        "publicURL": "http://23.253.72.207:8776/v1/fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "volume",
                "name": "cinder"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8773/services/Admin",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8773/services/Cloud",
                        "id": "289b59289d6048e2912b327e5d3240ca",
                        "publicURL": "http://23.253.72.207:8773/services/Cloud"
                    }
                ],
                "endpoints_links": [],
                "type": "ec2",
                "name": "ec2"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8080",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8080/v1/AUTH_fc394f2ab2df4114bde39905f800dc57",
                        "id": "16b76b5e5b7d48039a6e4cc3129545f3",
                        "publicURL": "http://23.253.72.207:8080/v1/AUTH_fc394f2ab2df4114bde39905f800dc57"
                    }
                ],
                "endpoints_links": [],
                "type": "object-store",
                "name": "swift"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://example.com/identity_v2_admin",
                        "region": "RegionOne",
                        "internalURL": "http://example.com/identity",
                        "id": "26af053673df4ef3a2340c4239e21ea2",
                        "publicURL": "http://example.com/identity"
                    }
                ],
                "endpoints_links": [],
                "type": "identity",
                "name": "keystone"
            }
        ],
        "user": {
            "username": "demo",
            "roles_links": [],
            "id": "9a6590b2ab024747bc2167c4e064d00d",
            "roles": [
                {
                    "name": "Member"
                },
                {
                    "name": "anotherrole"
                }
            ],
            "name": "demo"
        },
        "metadata": {
            "is_admin": 0,
            "roles": [
                "7598ac3c634d4c3da4b9126a5f67ca2b",
                "f95c0ab82d6045d9805033ee1fbc80d4"
            ]
        },
        "trust": {
            "id": "394998fa61f14736b1f0c1f322882949",
            "trustee_user_id": "269348fdd9374b8885da1418e0730af1",
            "trustor_user_id": "3ec3164f750146be97f21559ee4d9c51",
            "impersonation": false
        }
    }
}

API versions

GET
/v2.0
Show version details

Shows details for the Identity API v2.0.

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

Response Example

{
    "version": {
        "status": "stable",
        "updated": "2014-04-17T00:00:00Z",
        "media-types": [
            {
                "base": "application/json",
                "type": "application/vnd.openstack.identity-v2.0+json"
            }
        ],
        "id": "v2.0",
        "links": [
            {
                "href": "http://example.com/identity/v2.0/",
                "rel": "self"
            },
            {
                "href": "http://docs.openstack.org/",
                "rel": "describedby",
                "type": "text/html"
            }
        ]
    }
}
GET
/
List versions

Lists information about all Identity API versions.

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

Response Example

{
    "versions": {
        "values": [
            {
                "id": "v3.4",
                "links": [
                    {
                        "href": "http://example.com/identity/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": "http://example.com/identity/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"
            }
        ]
    }
}

API Details

Overview

The OpenStack Identity API is implemented using a RESTful web service interface. All requests to authenticate and operate against the OpenStack Identity API should be performed using HTTPS.

OpenStack Identity enables clients to obtain tokens that permit access to OpenStack cloud services.

Intended audience

This reference is for software developers who develop applications that use the Identity API for authentication.

This reference assumes that the reader is familiar with RESTful web services, HTTP/1.1, and JSON serialization formats.

Identity concepts

To use OpenStack Identity, you must be familiar with these key concepts:

User

A digital representation of a person, system, or service that uses OpenStack cloud services. OpenStack Identity authentication services validate that an incoming request is being made by the user who claims to be making the call.

Users have a login and may be assigned tokens to access resources. Users may be directly assigned to a particular tenant and behave as if they are contained in that tenant.

Token

An arbitrary bit of text that is used to access resources. Each token has a scope that describes which resources are accessible with it. A token may be revoked at anytime and is valid for a finite duration.

While OpenStack Identity supports token-based authentication, the intention is for it to support additional protocols in the future. The intent is for it to be an integration service foremost, and not aspire to be a full-fledged identity store and management solution.

Credentials

Data that belongs to, is owned by, and generally only known by a user that the user can present to prove their identity.

Examples include:

  • A matching username and password
  • A matching username and API key
  • A token that was issued to you
Authentication

In the context of the OpenStack Identity Service, the act of confirming the identity of a user or the truth of a claim. OpenStack Identity confirms that an incoming request is being made by the user who claims to be making the call by validating a set of identity information provided by the user.

These claims are initially in the form of a set of credentials (username & password, or username and API key). After initial confirmation, OpenStack Identity issues the user a token, which the user can then provide to demonstrate that their identity has been authenticated when making subsequent requests.

Tenant
A container used to group or isolate resources and/or identity objects. Depending on the service operator, a tenant can map to a customer, account, organization, or project.
Service
An OpenStack service, such as Compute (Nova), Object Storage (Swift), or Image Service (Glance). A service provides one or more endpoints through which users can access resources and perform operations.
Endpoint
A network-accessible address, usually described by a URL, where a service may be accessed. If using an extension for templates, you can create an endpoint template, which represents the templates of all the consumable services that are available across the regions.
Role

A personality that a user assumes when performing a specific set of operations. A role includes a set of rights and privileges. A user assuming that role inherits those rights and privileges.

In OpenStack Identity, a token that is issued to a user includes the list of roles that user can assume. Services that are being called by that user determine how they interpret the set of roles a user has and to which operations or resources each role grants access.

It is up to individual services such as the Compute service and Image service to assign meaning to these roles. As far as the Identity service is concerned, a role is an arbitrary name assigned by the user.

Paginated collections

To reduce load on the service, list operations return a maximum number of items at a time. The maximum number of items returned is determined by the Identity provider. To navigate the collection, you can set the ``limit`` and ``marker`` parameters in the URI. For example, ?``limit``=100&``marker``=1234. The ``marker`` parameter is the ID of the last item in the previous list. Items are sorted by update time. When an update time is not available they are sorted by ID. The ``limit`` parameter sets the page size. Both parameters are optional. If the client requests a ``limit`` beyond that which is supported by the deployment a 413 response code may be thrown. A marker with an invalid ID returns a 404 response code.

Note

Paginated collections will never return a 404 error when the collection is empty - clients should expect an empty collection.

For convenience, collections contain atom “next” and “previous” links. The first page in the list does not contain a previous link, the last page in the list does not contain a next link. The following examples illustrate three pages in a collection of tenants. The first page was retrieved through a GET to http://identity.api.openstack.org/v2.0/1234/tenants?limit=1. In these examples, the ``limit`` parameter sets the page size to a single item. Subsequent next and previous links honor the initial page size. Thus, a client might follow links to traverse a paginated collection without having to input the ``marker`` parameter.

Example: Tenant collection, first page:

{
    "tenants": [
        {
            "id": "1234",
            "name": "ACME corp",
            "description": "A description ...",
            "enabled": true
        }
    ],
    "tenants_links": [
        {
            "rel": "next",
            "href": "http://identity.api.openstack.org/v2.0/tenants?limit=1&marker=1234"
        }
    ]
}

Example: Tenant collection, second page:

{
    "tenants": [
        {
            "id": "3645",
            "name": "Iron Works",
            "description": "A description ...",
            "enabled": true
        }
    ],
    "tenants_links": [
        {
            "rel": "next",
            "href": "http://identity.api.openstack.org/v2.0/tenants?limit=1&marker=3645"
        },
        {
            "rel": "previous",
            "href": "http://identity.api.openstack.org/v2.0/tenants?limit=1"
        }
    ]
}

Example: Tenant collection, last page:

{
    "tenants": [
        {
            "id": "9999",
            "name": "Bigz",
            "description": "A description ...",
            "enabled": true
        }
    ],
    "tenants_links": [
        {
            "rel": "previous",
            "href": "http://identity.api.openstack.org/v2.0/tenants?limit=1&marker=1234"
        }
    ]
}

Paginated collections contain a values property that contains the items in the collections. Links are accessed via the links property. The approach allows for extensibility of both the collection members and of the paginated collection itself. It also allows collections to be embedded in other objects as illustrated below. Here, a subset of groups are presented within a user. Clients must follow the “next” link to continue to retrieve additional groups belonging to a user.

Example: Paginated roles in user:

{
    "user": {
        "OS-ROLE:roles": [
            {
                "tenantId": "1234",
                "id": "Admin"
            },
            {
                "tenantId": "1234",
                "id": "DBUser"
            }
        ],
        "OS-ROLE:roles_links": [
            {
                "rel": "next",
                "href": "http://identity.api.openstack.org/v2.0/tenants/1234/users/u1000/roles?marker=Super"
            }
        ],
        "id": "u1000",
        "username": "jqsmith",
        "email": "john.smith@example.org",
        "enabled": true
    }
}

Request and response formats

The OpenStack Identity API only supports JSON data serialization request and response formats.

Use the Content-Type request header to specify the request format. This header is required for operations that have a request body.

The syntax for the Content-Type header is:

Content-Type: application/json

Use the Accept header to specify the response format:

Accept: application/json

If you do not specify a response format, the Accept header will be set to application/json by default.