diff --git a/api-ref/source/index.inc b/api-ref/source/index.inc index 151dfe0f3e..a249b49584 100644 --- a/api-ref/source/index.inc +++ b/api-ref/source/index.inc @@ -11,6 +11,11 @@ Contents: .. toctree:: :maxdepth: 2 + v2-admin/admin-tenants.inc + v2-admin/admin-tokens.inc + v2-admin/admin-users.inc + v2-admin/admin-versions.inc + v2/identity-api-extensions.inc v2/identity-auth.inc v2/versions.inc diff --git a/api-ref/source/v2-admin/admin-tenants.inc b/api-ref/source/v2-admin/admin-tenants.inc new file mode 100644 index 0000000000..46a4b516b2 --- /dev/null +++ b/api-ref/source/v2-admin/admin-tenants.inc @@ -0,0 +1,106 @@ +.. -*- rst -*- + +======= +Tenants +======= + + +Show tenant details, by ID +========================== + +.. rest_method:: GET /v2.0/tenants/{tenantId} + +Shows details for a tenant, by ID. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenantId: tenantId + +Response Example +---------------- + +.. literalinclude:: samples/admin/tenant-show-response.json + :language: javascript + + +List roles for user +=================== + +.. rest_method:: GET /v2.0/tenants/{tenantId}/users/{userId}/roles + +Lists roles for a user on a tenant. Excludes global roles. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - userId: userId + - tenantId: tenantId + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - roles_links: roles_links + - roles: roles + - description: description + - name: name + - id: id + +Response Example +---------------- + +.. literalinclude:: samples/admin/roles-list-response.json + :language: javascript + + +List tenants (admin endpoint) +============================= + +.. rest_method:: GET /v2.0/tenants + +Lists all tenants. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Response Example +---------------- + +.. literalinclude:: ../v2/samples/admin/tenants-list-response.json + :language: javascript + + +Show tenant details, by name +============================ + +.. rest_method:: GET /v2.0/tenants + +Shows details for a tenant, by name. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: name + +Response Example +---------------- + +.. literalinclude:: samples/admin/tenant-show-response.json + :language: javascript diff --git a/api-ref/source/v2-admin/admin-tokens.inc b/api-ref/source/v2-admin/admin-tokens.inc new file mode 100644 index 0000000000..ae9e467ef3 --- /dev/null +++ b/api-ref/source/v2-admin/admin-tokens.inc @@ -0,0 +1,166 @@ +.. -*- rst -*- + +====== +Tokens +====== + + +List endoints for token +======================= + +.. rest_method:: GET /v2.0/tokens/{tokenId}/endpoints + +Lists the endpoints associated with a token. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tokenId: tokenId + +Response Example +---------------- + +.. literalinclude:: samples/admin/endpoints-list-response.json + :language: javascript + + +Authenticate for admin API +========================== + +.. rest_method:: POST /v2.0/tokens + +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 +``unauthorized (401)`` response code. + +If the token has expired, this call returns the ``itemNotFound +(404)`` response 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 Example +--------------- + +.. literalinclude:: ../v2/samples/admin/authenticate-token-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - impersonation: impersonation + - endpoints_links: endpoints_links + - serviceCatalog: serviceCatalog + - description: description + - type: type + - expires: expires + - enabled: enabled + - name: name + - access: access + - trustee_user_id: trustee_user_id + - token: token + - user: user + - issued_at: issued_at + - trustor_user_id: trustor_user_id + - endpoints: endpoints + - trust: trust + - id: id + - tenant: tenant + - metadata: metadata + +Response Example +---------------- + +.. literalinclude:: ../v2/samples/admin/authenticate-response.json + :language: javascript + + +Validate token +============== + +.. rest_method:: GET /v2.0/tokens/{tokenId} + +Validates a token and confirms that it belongs to a tenant. + +Returns the permissions relevant to a particular client. Valid +tokens are in the ``/tokens/{tokenId}`` path. If the token is not +valid, this call returns the ``itemNotFound (404)`` response code. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tokenId: tokenId + +Response Example +---------------- + +.. literalinclude:: samples/admin/token-validate-response.json + :language: javascript + + +Validate token (admin) +====================== + +.. rest_method:: HEAD /v2.0/tokens/{tokenId} + +Validates a token and confirms that it belongs to a tenant, for performance. + +Normal response codes: 200 +Error response codes:203,204,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tokenId: tokenId + + +Delete token +============ + +.. rest_method:: DELETE /v2.0/tokens/{tokenId} + +Deletes a token. + +Error response codes:204,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tokenId: tokenId diff --git a/api-ref/source/v2-admin/admin-users.inc b/api-ref/source/v2-admin/admin-users.inc new file mode 100644 index 0000000000..edaec188c0 --- /dev/null +++ b/api-ref/source/v2-admin/admin-users.inc @@ -0,0 +1,217 @@ +.. -*- rst -*- + +===== +Users +===== + + +List user global roles +====================== + +.. rest_method:: GET /v2.0/users/{userId}/roles + +Lists global roles for a user. Excludes tenant roles. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - userId: userId + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - roles_links: roles_links + - roles: roles + - description: description + - name: name + - id: id + +Response Example +---------------- + +.. literalinclude:: samples/admin/roles-list-response.json + :language: javascript + + +Create user (admin endpoint) +============================ + +.. rest_method:: POST /v2.0/users + +Creates a user. + +Error response codes:201,413,415,405,404,403,401,400,503,409, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenantId: tenantId + - password: password + - enabled: enabled + - email: email + - name: name + - X-Auth-Token: X-Auth-Token + +Request Example +--------------- + +.. literalinclude:: samples/admin/user-create-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - username: username + - enabled: enabled + - email: email + - name: name + - id: id + + +List users (admin endpoint) +=========================== + +.. rest_method:: GET /v2.0/users + +Lists all users. + +To show detailed information about a user by name, include the +``name`` query parameter in the request. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - username: username + - users: users + - enabled: enabled + - id: id + - email: email + - name: name + +Response Example +---------------- + +.. literalinclude:: samples/admin/user-show-response.json + :language: javascript + + +Update user (admin endpoint) +============================ + +.. rest_method:: PUT /v2.0/users/{userId} + +Updates a user. + +Error response codes:201,413,415,405,404,403,401,400,503,409, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - username: username + - enabled: enabled + - email: email + - name: name + - userId: userId + +Request Example +--------------- + +.. literalinclude:: samples/admin/user-update-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - enabled: enabled + - email: email + - name: name + - id: id + + +Delete user (admin endpoint) +============================ + +.. rest_method:: DELETE /v2.0/users/{userId} + +Deletes a user. + +Error response codes:204,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - userId: userId + + +Show user details (admin endpoint) +================================== + +.. rest_method:: GET /v2.0/users/{userId} + +Shows details for a user, by ID. + +The `openstack user show `_ command supports +showing user details by name or ID. However, the command actually +looks up the user ID for a user name and queries the user by ID. + +As a workaround, complete these steps to show details for a user by +name: + +- `List all users `_. + +- In the response, find the user name for which you want to show + details and note its corresponding user ID. + +- `Show details for user `_. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Request +------- + +.. rest_parameters:: parameters.yaml + + - userId: userId + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - username: username + - enabled: enabled + - email: email + - name: name + - id: id + +Response Example +---------------- + +.. literalinclude:: samples/admin/user-show-response.json + :language: javascript diff --git a/api-ref/source/v2-admin/admin-versions.inc b/api-ref/source/v2-admin/admin-versions.inc new file mode 100644 index 0000000000..aa89afdc39 --- /dev/null +++ b/api-ref/source/v2-admin/admin-versions.inc @@ -0,0 +1,29 @@ +.. -*- rst -*- + +======== +Versions +======== + + +Get version details +=================== + +.. rest_method:: GET /v2.0 + +Gets detailed information about a version of the Identity API. + +Normal response codes: 200 +Error response codes:203,413,405,404,403,401,400,503, + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - location: location + +Response Example +---------------- + +.. literalinclude:: ../v2/samples/admin/version-show-response.json + :language: javascript diff --git a/api-ref/source/v2-admin/parameters.yaml b/api-ref/source/v2-admin/parameters.yaml new file mode 100644 index 0000000000..eaa82be7b3 --- /dev/null +++ b/api-ref/source/v2-admin/parameters.yaml @@ -0,0 +1,270 @@ +# variables in header +X-Auth-Token: + description: | + A valid authentication token for an + administrative user. + in: header + required: true + type: string + +# variables in path +tenantId_1: + description: | + The tenant ID. + in: path + required: false + type: string +tokenId: + description: | + The authentication token for which to perform the + operation. + in: path + required: false + type: string +userId: + description: | + The user ID. + in: path + required: false + type: string + +# variables in query +name_2: + description: | + Filters the response by a tenant name. + in: query + required: true + type: string + +# variables in body +access: + description: | + An ``access`` object. + in: body + required: true + type: string +description: + description: | + The description of the tenant. If not set, this + value is ``null``. + in: body + required: true + type: string +email: + description: | + The user email. + in: body + required: false + type: string +email_1: + description: | + The user email. + in: body + required: true + type: string +enabled: + description: | + Indicates whether the tenant is enabled or + disabled. + in: body + required: true + type: boolean +enabled_1: + description: | + Indicates whether the user is enabled (``true``) + or disabled (``false``). Default is ``true``. + in: body + required: false + type: boolean +enabled_2: + description: | + Indicates whether the user is enabled (``true``) + or disabled(``false``). The default value is ``true``. + in: body + required: true + type: boolean +endpoints: + description: | + One or more ``endpoints`` objects. Each object + shows the ``adminURL``, ``region``, ``internalURL``, ``id``, and + ``publicURL`` for the endpoint. + in: body + required: true + type: string +endpoints_links: + description: | + Links for the endpoint. + in: body + required: true + type: string +expires: + description: | + 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. + in: body + required: true + type: string +id: + description: | + The ID of the trust. + in: body + required: false + type: string +id_1: + description: | + The user ID. + in: body + required: true + type: string +impersonation: + description: | + The impersonation flag. + in: body + required: false + type: string +issued_at: + description: | + 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``. + in: body + required: true + type: string +location: + format: uri + in: body + required: true + type: string +metadata: + description: | + A ``metadata`` object. + in: body + required: true + type: string +name: + description: | + Endpoint name. + in: body + required: true + type: string +name_1: + description: | + The user name. + in: body + required: true + type: string +password: + description: | + The user password. + in: body + required: false + type: string +roles: + description: | + The collection of roles. + in: body + required: true + type: array +roles_links: + description: | + The link to the represented role collection. + in: body + required: true + type: array +serviceCatalog: + description: | + A ``serviceCatalog`` object. + in: body + required: true + type: string +tenant: + description: | + A ``tenant`` object. + in: body + required: true + type: string +tenantId: + description: | + The tenant ID. + in: body + required: false + type: string +token: + description: | + A ``token`` object. + in: body + required: true + type: string +trust: + description: | + A ``trust`` object. + in: body + required: false + type: string +trustee_user_id: + description: | + The trustee user ID. + in: body + required: false + type: string +trustor_user_id: + description: | + The trustor user ID. + in: body + required: false + type: string +type: + description: | + Endpoint type. + in: body + required: true + type: string +user: + description: | + A ``user`` object, which shows the ``username``, + ``roles_links``, ``id``, ``roles``, and ``name``. + in: body + required: true + type: string +username: + description: | + The user name of the user. + in: body + required: true + type: string +username_1: + description: | + The username of user. + in: body + required: true + type: string +users: + description: | + One or more ``user`` objects. + in: body + required: true + type: array + diff --git a/api-ref/source/v2/samples/admin/endpoints-list-response.json b/api-ref/source/v2-admin/samples/admin/endpoints-list-response.json similarity index 100% rename from api-ref/source/v2/samples/admin/endpoints-list-response.json rename to api-ref/source/v2-admin/samples/admin/endpoints-list-response.json diff --git a/api-ref/source/v2/samples/admin/roles-list-response.json b/api-ref/source/v2-admin/samples/admin/roles-list-response.json similarity index 100% rename from api-ref/source/v2/samples/admin/roles-list-response.json rename to api-ref/source/v2-admin/samples/admin/roles-list-response.json diff --git a/api-ref/source/v2/samples/admin/tenant-show-response.json b/api-ref/source/v2-admin/samples/admin/tenant-show-response.json similarity index 100% rename from api-ref/source/v2/samples/admin/tenant-show-response.json rename to api-ref/source/v2-admin/samples/admin/tenant-show-response.json diff --git a/api-ref/source/v2/samples/admin/token-validate-response.json b/api-ref/source/v2-admin/samples/admin/token-validate-response.json similarity index 100% rename from api-ref/source/v2/samples/admin/token-validate-response.json rename to api-ref/source/v2-admin/samples/admin/token-validate-response.json diff --git a/api-ref/source/v2/samples/admin/user-create-request.json b/api-ref/source/v2-admin/samples/admin/user-create-request.json similarity index 100% rename from api-ref/source/v2/samples/admin/user-create-request.json rename to api-ref/source/v2-admin/samples/admin/user-create-request.json diff --git a/api-ref/source/v2/samples/admin/user-show-response.json b/api-ref/source/v2-admin/samples/admin/user-show-response.json similarity index 100% rename from api-ref/source/v2/samples/admin/user-show-response.json rename to api-ref/source/v2-admin/samples/admin/user-show-response.json diff --git a/api-ref/source/v2/samples/admin/user-update-request.json b/api-ref/source/v2-admin/samples/admin/user-update-request.json similarity index 100% rename from api-ref/source/v2/samples/admin/user-update-request.json rename to api-ref/source/v2-admin/samples/admin/user-update-request.json diff --git a/api-ref/source/v3-ext/inherit.inc b/api-ref/source/v3-ext/inherit.inc index a5a02d977c..2d8af3f235 100644 --- a/api-ref/source/v3-ext/inherit.inc +++ b/api-ref/source/v3-ext/inherit.inc @@ -413,8 +413,8 @@ Response Example :language: javascript -List roles for user -=================== +List inherited roles for user +============================= .. rest_method:: GET /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/inherited_to_projects