Vcenter Authentication Token issue

Vcenter Authentication Token issue

Provides a token endpoint as defined in RFC 6749.

Supported grant types:

This operation supercedes com.vmware.vcenter.tokenservice.TokenExchange#exchange. The REST rendering of the newer operation matches RFC8693's definition for both input and output of the operation.

This operation was added in vSphere API 7.0.2.0.

Request
URI
POST
https://{api_host}/api/vcenter/authentication/token
COPY
Request Body

Vcenter Authentication Token IssueSpec schema containing arguments that define the exchange process.

Vcenter Authentication Token IssueSpec of mimetype application/x-www-form-urlencoded
Required
string
grant_type
Required

The value of urn:ietf:params:oauth:grant-type:token-exchange indicates that a token exchange is being performed.

This property was added in vSphere API 7.0.2.0.

When clients pass a value of this schema as a parameter, the property must be one of urn:ietf:params:oauth:grant-type:token-exchange. When operations return a value of this schema as a response, the property will be one of urn:ietf:params:oauth:grant-type:token-exchange.

string
resource
Optional

Indicates the location of the target service or resource where the client intends to use the requested security token.

This property was added in vSphere API 7.0.2.0.

If missing or null, it is inferred from other arguments.

string
audience
Optional

The logical name of the target service where the client intends to use the requested security token. This serves a purpose similar to the Vcenter Authentication Token IssueSpec.resource property, but with the client providing a logical name rather than a location.

This property was added in vSphere API 7.0.2.0.

If missing or null, it is inferred from other arguments.

string
scope
Optional

A list of space-delimited, case-sensitive strings, that allow the client to specify the desired scope of the requested security token in the context of the service or resource where the token will be used.

This property was added in vSphere API 7.0.2.0.

If missing or null, it is inferred from other arguments.

string
requested_token_type
Optional

An identifier for the type of the requested security token. If the requested type is unspecified, the issued token type is at the discretion of the server and may be dictated by knowledge of the requirements of the service or resource indicated by the Vcenter Authentication Token IssueSpec.resource or Vcenter Authentication Token IssueSpec.audience property.

This property was added in vSphere API 7.0.2.0.

If missing or null, it is inferred from other arguments.

string
subject_token
Optional

A security token that represents the identity of the party on behalf of whom exchange is being made. Typically, the subject of this token will be the subject of the security token issued. Token is base64-encoded.

The property is required when the value of the Vcenter Authentication Token IssueSpec.grant_type property is urn:ietf:params:oauth:grant-type:token-exchange.

This property was added in vSphere API 7.0.2.0.

This property is currently required. In the future, the schema may support grant-types other than urn:ietf:params:oauth:grant-type:token-exchange for which the value may be missing or null.

string
subject_token_type
Optional

An identifier, that indicates the type of the security token in the Vcenter Authentication Token IssueSpec.subject_token property.

The property is required when the value of the Vcenter Authentication Token IssueSpec.grant_type property is urn:ietf:params:oauth:grant-type:token-exchange.

This property was added in vSphere API 7.0.2.0.

This property is currently required. In the future, the schema may support grant-types other than urn:ietf:params:oauth:grant-type:token-exchange for which the value may be missing or null.

string
actor_token
Optional

A security token that represents the identity of the acting party. Typically, this will be the party that is authorized to use the requested security token and act on behalf of the subject.

This property was added in vSphere API 7.0.2.0.

missing or null if not needed for the specific case of exchange.

string
actor_token_type
Optional

An identifier, that indicates the type of the security token in the Vcenter Authentication Token IssueSpec.actor_token property.

This property was added in vSphere API 7.0.2.0.

missing or null if Vcenter Authentication Token IssueSpec.actor_token property is not present.

Authentication
This operation uses the following authentication methods.
Responses
200

Oauth2 TokenInfo schema that contains a newly issued token.

Returns Oauth2 TokenInfo of type(s) application/json
"Oauth2 TokenInfo Object"
string
access_token
Required

The access token issued by the authorization server.

This property was added in vSphere API 7.0.2.0.

string
token_type
Required

A case-insensitive value specifying the method of using the access token issued.

This property was added in vSphere API 7.0.2.0.

integer As int64 As int64
expires_in
Optional

The validity lifetime, in seconds, of the token issued by the server.

This property was added in vSphere API 7.0.2.0.

missing or null if not applicable for issued token.

string
scope
Optional

Scope of the issued access token. The value of the scope parameter is expressed as a list of space- delimited, case-sensitive strings. The strings are defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.

This property was added in vSphere API 7.0.2.0.

missing or null if the scope of the issued security token is identical to the scope requested by the client.

string
refresh_token
Optional

The refresh token, which can be used to obtain new access tokens.

This property was added in vSphere API 7.0.2.0.

missing or null if not applicable to the specific request.

string
issued_token_type
Optional

An identifier which indicates the type of the access token in the Oauth2 TokenInfo.access_token property.

This property was added in vSphere API 7.0.2.0.

missing or null if not the result of a token-exchange invocation; otherwise, required.


400

Oauth2 Errors InvalidRequest if Vcenter Authentication Token IssueSpec is missing a required property, includes an unsupported property value (other than Vcenter Authentication Token IssueSpec.grant_type).

Oauth2 Errors InvalidGrant provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

Oauth2 Errors InvalidScope If the server is unwilling or unable to issue a token for all the target services indicated by the Vcenter Authentication Token IssueSpec.resource or Vcenter Authentication Token IssueSpec.audience properties.

Returns Oauth2 Errors Error of type(s) application/json
"Oauth2 Errors Error Object"
string
error
Required

Discriminator field to help API consumers identify the structure type.

For more information see: Oauth2 Errors Error Type.

This property was added in vSphere API 7.0.2.0.

string
error_description
Optional

Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

This property was added in vSphere API 7.0.2.0.

if no additional information is available.

string As uri As uri
error_uri
Optional

A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

This property was added in vSphere API 7.0.2.0.

if no such web-page is available.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/x-www-form-urlencoded' -d '{"grant_type:"string"}' https://{api_host}/api/vcenter/authentication/token