Create Authentication Token

Create Authentication Token

Provides a token endpoint as defined in RFC 6749. Supported grant types:

  • urn:ietf:params:oauth:grant-type:token-exchange - Exchanges incoming token based on the spec and current client authorization data.

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.

Request
URI
POST
https://{api_host}/api/vcenter/authentication/token
COPY
Request Body
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. When clients pass a value of this structure as a parameter, the field must be one of urn:ietf:params:oauth:grant-type:token-exchange. When operations return a value of this structure as a result, the field 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. If unset, 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 Token.IssueSpec.resource field, but with the client providing a logical name rather than a location. If unset, 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. If unset, 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 Token.IssueSpec.resource or Token.IssueSpec.audience field. If unset, it is inferred from other arguments.

string
subject_token
Required

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 field is required when the value of the Token.IssueSpec.grant-type field is urn:ietf:params:oauth:grant-type:token-exchange.

This field is currently required. In the future, the structure may support grant-types other than urn:ietf:params:oauth:grant-type:token-exchange for which the value may be unset.

string
subject_token_type
Required

An identifier, that indicates the type of the security token in the Token.IssueSpec.subject-token field. The field is required when the value of the Token.IssueSpec.grant-type field is urn:ietf:params:oauth:grant-type:token-exchange.

This field is currently required. In the future, the structure may support grant-types other than urn:ietf:params:oauth:grant-type:token-exchange for which the value may be unset.

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. unset 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 Token.IssueSpec.actor-token field. unset if Token.IssueSpec.actor-token field is not present.

Authentication
This operation uses the following authentication methods.
Responses
200

TokenInfo structure that contains a newly issued token.

Returns Oauth2_TokenInfo of type(s) application/json
{
    "access_token": "string",
    "token_type": "string",
    "expires_in": 0,
    "scope": "string",
    "refresh_token": "string",
    "issued_token_type": "string"
}
string
access_token
Required

The access token issued by the authorization server.

string
token_type
Required

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

integer As int64
expires_in
Optional

The validity lifetime, in seconds, of the token issued by the server. unset 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. unset 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. unset if not applicable to the specific request.

string
issued_token_type
Optional

An identifier which indicates the type of the access token in the TokenInfo.access-token field. unset if not the result of a token-exchange invocation; otherwise, required.


400

com.vmware.vcenter.oauth2.errors.invalid_request : if Token.IssueSpec is missing a required field, includes an unsupported field value (other than Token.IssueSpec.grant-type). | com.vmware.vcenter.oauth2.errors.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. | com.vmware.vcenter.oauth2.errors.invalid_scope : If the server is unwilling or unable to issue a token for all the target services indicated by the Token.IssueSpec.resource or Token.IssueSpec.audience fields.

Returns Oauth2_Errors_Error of type(s) application/json
{
    "error": "string",
    "error_description": "string",
    "error_uri": "string"
}
error
Required

Enumeration of OAuth 2.0 errors.
invalid_request : Discriminator for the InvalidRequest type.
invalid_scope : Discriminator for the InvalidScope type.
invalid_grant : Discriminator for the InvalidGrant type.
invalid_client : Discriminator for the InvalidClient type.
unauthorized_client : Discriminator for the UnauthorizedClient type.
unsupported_grant_type : Discriminator for the UnsupportedGrantType type.
invalid_target : Discriminator for the InvalidTarget type

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. if no additional information is available.

string 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. if no such web-page is available.


default

'Default' means this response is used for all HTTP codes that are not covered individually for this operation.

Returns Std_Errors_Error of type(s) application/json
{
    "messages": [
        {
            "id": "string",
            "default_message": "string",
            "args": [
                "string"
            ],
            "params": {
                "params": {
                    "s": "string",
                    "dt": "string",
                    "i": 0,
                    "d": "number",
                    "l": {
                        "id": "string",
                        "params": {
                            "params": "Std_LocalizationParam Object"
                        }
                    },
                    "format": "string",
                    "precision": 0
                }
            },
            "localized": "string"
        }
    ],
    "data": {},
    "error_type": "string"
}
messages
Required

Stack of one or more localizable messages for human error consumers. The message at the top of the stack (first in the list) describes the error from the perspective of the operation the client invoked.

Each subsequent message in the stack describes the "cause" of the prior message.

object
data
Optional

Data to facilitate clients responding to the operation reporting a standard error to indicating that it was unable to complete successfully. Operations may provide data that clients can use when responding to errors. Since the data that clients need may be specific to the context of the operation reporting the error, different operations that report the same error may provide different data in the error. The documentation for each each operation will describe what, if any, data it provides for each error it reports.

The ArgumentLocations, FileLocations, and TransientIndication structures are intended as possible values for this field. DynamicID may also be useful as a value for this field (although that is not its primary purpose). Some services may provide their own specific structures for use as the value of this field when reporting errors from their operations.

Some operations will not set this field when reporting errors.

error_type
Optional

Enumeration of all standard errors. Used as discriminator in protocols that have no standard means for transporting the error type, e.g. REST.
ERROR : Discriminator for the Error type.
ALREADY_EXISTS : Discriminator for the AlreadyExists type.
ALREADY_IN_DESIRED_STATE : Discriminator for the AlreadyInDesiredState type.
CANCELED : Discriminator for the Canceled type.
CONCURRENT_CHANGE : Discriminator for the ConcurrentChange type.
FEATURE_IN_USE : Discriminator for the FeatureInUse type.
INTERNAL_SERVER_ERROR : Discriminator for the InternalServerError type.
INVALID_ARGUMENT : Discriminator for the InvalidArgument type.
INVALID_ELEMENT_CONFIGURATION : Discriminator for the InvalidElementConfiguration type.
INVALID_ELEMENT_TYPE : Discriminator for the InvalidElementType type.
INVALID_REQUEST : Discriminator for the InvalidRequest type.
NOT_ALLOWED_IN_CURRENT_STATE : Discriminator for the NotAllowedInCurrentState type.
NOT_FOUND : Discriminator for the NotFound type.
OPERATION_NOT_FOUND : Discriminator for the OperationNotFound type.
RESOURCE_BUSY : Discriminator for the ResourceBusy type.
RESOURCE_IN_USE : Discriminator for the ResourceInUse type.
RESOURCE_INACCESSIBLE : Discriminator for the ResourceInaccessible type.
SERVICE_UNAVAILABLE : Discriminator for the ServiceUnavailable type.
TIMED_OUT : Discriminator for the TimedOut type.
UNABLE_TO_ALLOCATE_RESOURCE : Discriminator for the UnableToAllocateResource type.
UNAUTHENTICATED : Discriminator for the Unauthenticated type.
UNAUTHORIZED : Discriminator for the Unauthorized type.
UNEXPECTED_INPUT : Discriminator for the UnexpectedInput type.
UNSUPPORTED : Discriminator for the Unsupported type.
UNVERIFIED_PEER : Discriminator for the UnverifiedPeer type.


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

# Module 'VMware.Sdk.vSphere.vCenter.Authentication'

Invoke-CreateAuthenticationToken -GrantType "MyGrantType" -SubjectToken "MySubjectToken" -SubjectTokenType "MySubjectTokenType"

# Module 'VMware.Sdk.vSphere.vCenter.Authentication'

Invoke-CreateAuthenticationToken -GrantType "MyGrantType" -SubjectToken "MySubjectToken" -SubjectTokenType "MySubjectTokenType" -Resource "MyResource" -Audience "MyAudience" -Scope "MyScope" -RequestedTokenType "MyRequestedTokenType" -ActorToken "MyActorToken" -ActorTokenType "MyActorTokenType"