REST API - exchange

vcenter tokenservice token exchange: exchange

Exchanges incoming token based on the spec and current client authorization data.

Request:

HTTP request

POST https://{server}/rest/vcenter/tokenservice/token-exchange

Request Body Structure:

{
    "spec" : {
        "subject_token_type" : "string",
        "audience" : "string",
        "actor_token" : "string",
        "grant_type" : "string",
        "resource" : "string",
        "scope" : "string",
        "subject_token" : "string",
        "requested_token_type" : "string",
        "actor_token_type" : "string"
    }
}

Request Body Parameters:

Name	Type	Description
bold = required
spec	exchange_spec	`exchange_spec` structure contains arguments that define exchange process.
spec.grant_type	string	The value of TOKEN_EXCHANGE_GRANT indicates that a token exchange is being performed.
spec.resource	string	Indicates the location of the target service or resource where the client intends to use the requested security token. Optional. if can be inferred from other arguments or not needed for specific case of exchange.
spec.audience	string	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.tokenservice.token_exchange.exchange_spec.resource parameter, but with the client providing a logical name rather than a location. Optional. if can be inferred from other arguments or not needed for specific case of exchange.
spec.scope	string	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. Optional. if can be inferred from other arguments or not needed for specific case of exchange.
spec.requested_token_type	string	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.tokenservice.token_exchange.exchange_spec.resource or vcenter.tokenservice.token_exchange.exchange_spec.audience parameter. Optional. if can be inferred from other arguments or not needed for specific case of exchange.
spec.subject_token	string	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.
spec.subject_token_type	string	An identifier, that indicates the type of the security token in the vcenter.tokenservice.token_exchange.exchange_spec.subject_token parameter.
spec.actor_token	string	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. Optional. if not needed for specific case of exchange.
spec.actor_token_type	string	An identifier, that indicates the type of the security token in the vcenter.tokenservice.token_exchange.exchange_spec.actor_token parameter. Optional. if vcenter.tokenservice.token_exchange.exchange_spec.actor_token parameter is not present.

Response:

HTTP Status Code: 200

Representation:

{
    "value" : {
        "access_token" : "string",
        "refresh_token" : "string",
        "issued_token_type" : "string",
        "scope" : "string",
        "token_type" : "string",
        "expires_in" : 1
    }
}

Response Type:

Name	Type	Description
bold = required
value	info	vcenter.tokenservice.token_exchange.info structure that contains new token.
value.access_token	string	The security token issued by the server in response to the token exchange request. Token is base64-encoded.
value.issued_token_type	string	An identifier, that indicates the type of the security token in the vcenter.tokenservice.token_exchange.info.access_token parameter.
value.token_type	string	A case-insensitive value specifying the method of using the access token issued.
value.expires_in	long	The validity lifetime, in seconds, of the token issued by the server. Optional. if not applicable for issued token.
value.scope	string	Scope of the issued security token. Optional. if the scope of the issued security token is identical to the scope requested by the client.
value.refresh_token	string	A refresh token can be issued in cases where the client of the token exchange needs the ability to access a resource even when the original credential is no longer valid. Optional. if not needed for specific case of exchange.

Errors:

HTTP Status Code	Type	Description
400	invalid_request
500	invalid_request
500	invalid_grant	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.
500	invalid_scope	If the server is unwilling or unable to issue a token for all the target services indicated by the vcenter.tokenservice.token_exchange.exchange_spec.resource or vcenter.tokenservice.token_exchange.exchange_spec.audience parameters.
403	unauthorized	if authorization is not given to a caller.