Identity Admin API v2.0 (SUPPORTED)

Gets an authentication token that permits access to the Compute API.

Versions

GET
/v2.0
Get version details

Gets detailed information about a specified version of the Identity API.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Response parameters
Parameter Style Type Description
location plain xsd:anyURI 
{
    "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://localhost:5000/v2.0/",
                "rel": "self"
            },
            {
                "href": "http://docs.openstack.org/",
                "rel": "describedby",
                "type": "text/html"
            }
        ]
    }
}

This operation does not accept a request body.

Tokens

POST
/v2.0/tokens
Authenticate for admin API

Authenticates and generates a token.

 

A REST interface provides client authentication by using the POST method with v2.0/tokens as the path. Include a payload of credentials in the body.

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

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

If the token specified in the request body 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.

Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), userDisabled (403), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenantName (Optional) plain xsd:string

The tenant name. Both the tenantId and tenantName attributes are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.

tenantId (Optional) plain capi:UUID

The tenant ID. Both the tenantId and tenantName attributes are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.

passwordCredentials (Optional) plain xsd:string

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

username (Optional) plain xsd:string

The user name. Required if you include the passwordCredentials object. If you do not provide a password credentials, you must provide a token.

password (Optional) plain xsd:string

The password of the user. Required if you include the passwordCredentials object. If you do not provide a password credentials, you must provide a token.

token (Optional) plain xsd:string

A token object. Required if you do not provide password credentials.

id (Optional) plain xsd:string

The token ID. This is a required field in the token object.

Response parameters
Parameter Style Type Description
access plain xsd:string

An access object.

token plain xsd:string

A token object.

issued_at plain xsd:string

A time stamp that indicates when the token was issued.

expires plain xsd:string

A time stamp that indicates when the token expires.

id plain xsd:string

The authentication token. In the example, the token is my_id.

tenant plain xsd:string

A tenant object.

description plain xsd:string

The description of the tenant. If not set, this value is null.

enabled plain xsd:boolean

Indicates whether the tenant is enabled or disabled.

id plain xsd:string

The tenant ID.

name plain xsd:string

The tenant name.

serviceCatalog plain xsd:string

A serviceCatalog object.

endpoints plain xsd:string

One or more endpoints objects. Each object shows the adminURL, region, internalURL, id, and publicURL for the endpoint.

endpoints_links plain xsd:string

Links for the endpoint.

type plain xsd:string

Endpoint type.

name plain xsd:string

Endpoint name.

user plain xsd:string

A user object, which shows the username, roles_links, id, roles, and name.

metadata plain xsd:string

A metadata object. 

{
    "auth": {
        "tenantName": "admin",
        "passwordCredentials": {
            "username": "admin",
            "password": "secretsecret"
        }
    }
}

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

{
    "access": {
        "token": {
            "issued_at": "2014-01-30T17:09:57.647795",
            "expires": "2014-01-31T17:09:57Z",
            "id": "admin_id",
            "tenant": {
                "description": null,
                "enabled": true,
                "id": "73f0aa26640f4971864919d0eb0f0880",
                "name": "admin"
            }
        },
        "serviceCatalog": [
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:8774/v2/73f0aa26640f4971864919d0eb0f0880",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8774/v2/73f0aa26640f4971864919d0eb0f0880",
                        "id": "2dad48f09e2a447a9bf852bcd93548ef",
                        "publicURL": "http://23.253.72.207:8774/v2/73f0aa26640f4971864919d0eb0f0880"
                    }
                ],
                "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/73f0aa26640f4971864919d0eb0f0880",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8776/v2/73f0aa26640f4971864919d0eb0f0880",
                        "id": "93f86dfcbba143a39a33d0c2cd424870",
                        "publicURL": "http://23.253.72.207:8776/v2/73f0aa26640f4971864919d0eb0f0880"
                    }
                ],
                "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/73f0aa26640f4971864919d0eb0f0880",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:8776/v1/73f0aa26640f4971864919d0eb0f0880",
                        "id": "37c83a2157f944f1972e74658aa0b139",
                        "publicURL": "http://23.253.72.207:8776/v1/73f0aa26640f4971864919d0eb0f0880"
                    }
                ],
                "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_73f0aa26640f4971864919d0eb0f0880",
                        "id": "16b76b5e5b7d48039a6e4cc3129545f3",
                        "publicURL": "http://23.253.72.207:8080/v1/AUTH_73f0aa26640f4971864919d0eb0f0880"
                    }
                ],
                "endpoints_links": [],
                "type": "object-store",
                "name": "swift"
            },
            {
                "endpoints": [
                    {
                        "adminURL": "http://23.253.72.207:35357/v2.0",
                        "region": "RegionOne",
                        "internalURL": "http://23.253.72.207:5000/v2.0",
                        "id": "26af053673df4ef3a2340c4239e21ea2",
                        "publicURL": "http://23.253.72.207:5000/v2.0"
                    }
                ],
                "endpoints_links": [],
                "type": "identity",
                "name": "keystone"
            }
        ],
        "user": {
            "username": "admin",
            "roles_links": [],
            "id": "1f568815cb8148688e6ee9b2f7527dcc",
            "roles": [
                {
                    "name": "service"
                },
                {
                    "name": "admin"
                }
            ],
            "name": "admin"
        },
        "metadata": {
            "is_admin": 0,
            "roles": [
                "8341d3603a1d4d5985bff09f10704d4d",
                "2e66d57df76946fdbe034bc4da6fdec0"
            ]
        }
    }
}
GET
/v2.0/tokens/​{tokenId}​
Validate token

Validates a token and confirms that it belongs to a specified tenant.

 

Returns the permissions relevant to a particular client. Valid tokens are in the /tokens/{tokenId} path. A user should expect an itemNotFound (404) fault for a token that is not valid.

Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
tokenId URI capi:UUID Required. The token ID.
belongsTo (Optional) query xsd:string

Validates that a token has the specified tenant in scope, for performance. Valid tokens are in the /tokens/{tokenId} path. If the token is not valid, this call returns the HTTP itemNotFound (404) status code. 

{
    "access": {
        "token": {
            "id": "ab48a9efdfedb23ty3494",
            "expires": "2010-11-01T03:32:15-05:00",
            "tenant": {
                "id": "345",
                "name": "My Project"
            }
        },
        "user": {
            "id": "123",
            "name": "jqsmith",
            "roles": [
                {
                    "id": "234",
                    "name": "compute:admin"
                },
                {
                    "id": "234",
                    "name": "object-store:admin",
                    "tenantId": "1"
                }
            ],
            "roles_links": []
        }
    }
}

This operation does not accept a request body.

HEAD
/v2.0/tokens/​{tokenId}​
Validate token (admin)

Validates a token and confirms that it belongs to a specified tenant, for performance.

 
Normal response codes
200, 203, 204
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
tokenId URI capi:UUID Required. The token ID.
belongsTo (Optional) query xsd:string

Validates that a token has the specified tenant in scope, for performance. Valid tokens are in the /tokens/{tokenId} path. If the token is not valid, this call returns the HTTP itemNotFound (404) status code.

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

Users

POST
/v2.0/users
Create user

Creates a user.

 
Normal response codes
201
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404), badMediaType (415)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string A valid authentication token for an administrative user.
tenantId plain xsd:string The tenant ID.
name plain xsd:string The user name.
email plain xsd:string The user email.
password plain xsd:string The user password.
enabled plain xsd:bool Indicates whether the user is enabled (true) or disabled (false).
Response parameters
Parameter Style Type Description
id plain xsd:string The user ID.
name plain xsd:string The user name.
email plain xsd:string The user email.
username plain xsd:string The user username.
enabled plain xsd:bool Indicates whether the user is enabled (true) or disabled (false). 
{
    "user": {
        "tenantId": "null",
        "name": "jqsmith",
        "email": "john.smith@example.org",
        "password": "null",
        "enabled": true
    }
}

{
    "user": {
        "id": "u1000",
        "name": "jqsmith",
        "email": "john.smith@example.org",
        "enabled": true,
        "username": "jqsmith"
    }
}
GET
/v2.0/users
Get user information by name

Gets detailed information about a specified user by user name.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
name query xsd:string Required. The user name. Specify the name query parameter as follows: GET /v2.0/users?name={name}. 
{
    "user": {
        "email": "john.smith@example.org",
        "enabled": true,
        "id": "u1000",
        "name": "jqsmith",
        "username": "jqsmith"
    }
}
PUT
/v2.0/users/​{userId}​
Update user

Updates a user.

 
Normal response codes
201
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415), itemNotFound (404)
Request parameters
Parameter Style Type Description
userId URI xsd:string

The ID of the user for which you want to perform the request.

id plain xsd:string The user ID.
name plain xsd:string The user name.
email plain xsd:string The user email.
enabled plain xsd:bool Indicates whether the user is enabled (true) or disabled (false).
Response parameters
Parameter Style Type Description
id plain xsd:string The user ID.
name plain xsd:string The user name.
email plain xsd:string The user email.
enabled plain xsd:bool Indicates whether the user is enabled (true) or disabled (false). 
{
    "user": {
        "email": "john.smith@example.org",
        "enabled": true,
        "id": "u1000",
        "name": "jqsmith",
        "username": "jqsmith"
    }
}

{
    "user": {
        "email": "john.smith@example.org",
        "enabled": true,
        "id": "u1000",
        "name": "jqsmith",
        "username": "jqsmith"
    }
}
DELETE
/v2.0/users/​{userId}​
Delete user

Deletes a user.

 
Normal response codes
204
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
userId URI xsd:string

The ID of the user for which you want to perform the request.

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

GET
/v2.0/users/​{user_id}​
Get user information by ID

Gets detailed information about a specified user by user ID.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
user_id URI xsd:string The user ID. 
{
    "user": {
        "email": "john.smith@example.org",
        "enabled": true,
        "id": "u1000",
        "name": "jqsmith",
        "username": "jqsmith"
    }
}

This operation does not accept a request body.

GET
/v2.0/users/​{user_id}​/roles
List user global roles

Lists global roles for a specified user. Excludes tenant roles.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
user_id URI xsd:string The user ID.
limit (Optional) query xsd:int

Requests a specified page size of returned items from the query. Returns a number of items up to the specified 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 xsd:string

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

{
    "roles": [
        {
            "id": "123",
            "name": "compute:admin",
            "description": "Nova Administrator"
        }
    ],
    "roles_links": []
}

Tenants

GET
/v2.0/tenants
List tenants

Lists all tenants.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string A valid authentication token for an administrative user.
limit (Optional) query xsd:int

Requests a specified page size of returned items from the query. Returns a number of items up to the specified 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 xsd:string

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

{
    "tenants": [
        {
            "id": "1234",
            "name": "ACME Corp",
            "description": "A description ...",
            "enabled": true
        },
        {
            "id": "3456",
            "name": "Iron Works",
            "description": "A description ...",
            "enabled": true
        }
    ],
    "tenants_links": []
}
GET
/v2.0/tenants
Get tenant information by name

Gets detailed information about a specified tenant by name.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string A valid authentication token for an administrative user.
name query xsd:string The name of the tenant. 
{
    "tenant": {
        "id": "1234",
        "name": "ACME corp",
        "description": "A description ...",
        "enabled": true
    }
}
GET
/v2.0/tenants/​{tenantId}​
Get tenant information by ID

Gets detailed information about a specified tenant by ID.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string A valid authentication token for an administrative user.
tenantId URI xsd:string The tenant ID. 
{
    "tenant": {
        "id": "1234",
        "name": "ACME corp",
        "description": "A description ...",
        "enabled": true
    }
}

This operation does not accept a request body.

GET
/v2.0/tenants/​{tenantId}​/users/​{userId}​/roles
List roles for user

Lists roles for a specified user on a specified tenant. Excludes global roles.

 
Normal response codes
200, 203
Error response codes
identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)
Request parameters
Parameter Style Type Description
X-Auth-Token header xsd:string A valid authentication token for an administrative user.
tenantId URI xsd:string The tenant ID.
userId URI xsd:string The user ID.
limit (Optional) query xsd:int

Requests a specified page size of returned items from the query. Returns a number of items up to the specified 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 xsd:string

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

{
    "roles": [
        {
            "id": "123",
            "name": "compute:admin",
            "description": "Nova Administrator"
        }
    ],
    "roles_links": []
}