CreateOAuth2Token

$result = $client->createOAuth2Token([/* ... */]);
$promise = $client->createOAuth2TokenAsync([/* ... */]);

CreateOAuth2Token API

Path: /v1/token Request Method: POST Content-Type: application/json or application/x-www-form-urlencoded

This API implements OAuth 2.0 flows for AWS Sign-In CLI clients, supporting both:

1. Authorization code redemption (grant_type=authorization_code) - NOT idempotent
2. Token refresh (grant_type=refresh_token) - Idempotent within token validity window

The operation behavior is determined by the grant_type parameter in the request body:

Authorization Code Flow (NOT Idempotent):

• JSON or form-encoded body with client_id, grant_type=authorization_code, code, redirect_uri, code_verifier
• Returns access_token, token_type, expires_in, refresh_token, and id_token
• Each authorization code can only be used ONCE for security (prevents replay attacks)

Token Refresh Flow (Idempotent):

• JSON or form-encoded body with client_id, grant_type=refresh_token, refresh_token
• Returns access_token, token_type, expires_in, and refresh_token (no id_token)
• Multiple calls with same refresh_token return consistent results within validity window

Authentication and authorization:

• Confidential clients: sigv4 signing required with signin:ExchangeToken permissions
• CLI clients (public): authn/authz skipped based on client_id & grant_type

Note: This operation cannot be marked as @idempotent because it handles both idempotent (token refresh) and non-idempotent (auth code redemption) flows in a single endpoint.

Parameter Syntax

$result = $client->createOAuth2Token([
    'tokenInput' => [ // REQUIRED
        'clientId' => '<string>', // REQUIRED
        'code' => '<string>',
        'codeVerifier' => '<string>',
        'grantType' => '<string>', // REQUIRED
        'redirectUri' => '<string>',
        'refreshToken' => '<string>',
    ],
]);

Parameter Details

Result Syntax

[
    'tokenOutput' => [
        'accessToken' => [
            'accessKeyId' => '<string>',
            'secretAccessKey' => '<string>',
            'sessionToken' => '<string>',
        ],
        'expiresIn' => <integer>,
        'idToken' => '<string>',
        'refreshToken' => '<string>',
        'tokenType' => '<string>',
    ],
]

Result Details

Errors

TooManyRequestsError:

Error thrown when rate limit is exceeded

HTTP Status Code: 429 Too Many Requests

Possible OAuth2ErrorCode values:

• INVALID_REQUEST: Rate limiting, too many requests, abuse prevention

Possible causes:

• Too many token requests from the same client
• Rate limiting based on client_id or IP address
• Abuse prevention mechanisms triggered
• Service protection against excessive token generation

InternalServerException:

Error thrown when an internal server error occurs

HTTP Status Code: 500 Internal Server Error

Used for unexpected server-side errors that prevent request processing.

ValidationException:

Error thrown when request validation fails

HTTP Status Code: 400 Bad Request

Used for request validation errors such as malformed parameters, missing required fields, or invalid parameter values.

AccessDeniedException:

Error thrown for access denied scenarios with flexible HTTP status mapping

Runtime HTTP Status Code Mapping:

• HTTP 401 (Unauthorized): TOKEN_EXPIRED, AUTHCODE_EXPIRED
• HTTP 403 (Forbidden): USER_CREDENTIALS_CHANGED, INSUFFICIENT_PERMISSIONS

The specific HTTP status code is determined at runtime based on the error enum value. Consumers should use the error field to determine the specific access denial reason.