Request Syntax Request Parameters Request Body Response Syntax Response Elements Errors See Also

AuthorizeOAuth2Access

Grants permission to authenticate through a browser and obtain an OAuth 2.0 authorization code for credential exchange.

Request Syntax


GET /v1/authorize?client_id=clientId&code_challenge=codeChallenge&code_challenge_method=codeChallengeMethod&redirect_uri=redirectUri&resource=resource&response_type=responseType&scope=scope&state=state HTTP/1.1

Request Parameters

The request uses the following request parameters.

clientId

Client identifier which is unique to authorization server. Expected values: arn:aws:signin:::devtools/same-device, arn:aws:signin:::devtools/cross-device, or arn:aws:signin:{region}::external-client/dcr/{uuid} for dynamically registered clients.

Pattern: arn:aws:signin:::devtools/(same-device|cross-device)$|^arn:aws:signin:[^:]*::external-client/dcr/.*

Required: Yes

codeChallenge

PKCE code challenge (SHA-256 hash of code verifier). Base64URL encoded, 43-128 characters.

Length Constraints: Minimum length of 43. Maximum length of 128.

Pattern: [A-Za-z0-9\-._~]+

Required: Yes

codeChallengeMethod

PKCE code challenge method - must be SHA-256 for AWS CLI.

Pattern: SHA-256

Required: Yes

redirectUri

Redirect URI where authorization code will be sent.

Same-device: http://127.0.0.1:PORT/oauth/callback

Cross-device: https://{region}.signin.aws.amazon.com/v1/sessions/confirmation

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

resource

The OAuth resource for which the access token is requested. This identifies the target service that the token grants access to. To scope the access token down to the specific resource, the resource parameter is mandated under RFC 8707 (Resource Indicators for OAuth 2.0).

If the client is a dynamically registered (DCR) client, this parameter is required.

Example: https://aws-mcp.us-east-1.api.aws/mcp.

Length Constraints: Minimum length of 1. Maximum length of 2048.

responseType

OAuth 2.0 response type - must be code for authorization code flow.

Pattern: code

Required: Yes

scope

OAuth 2.0 scope parameter - must be openid for AWS CLI clients.

Pattern: openid

state

CSRF protection parameter to prevent authorization injection attacks.

Length Constraints: Minimum length of 1. Maximum length of 128.

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 302
Location: location

Response Elements

If the action is successful, the service sends back an HTTP 302 response.

The response returns the following HTTP headers.

location

HTTP Location header containing the redirect URI with authorization code and state parameters.

Response format: {redirect_uri}?code={authorization_code}&state={state_parameter}

Where:

redirect_uri: The same URI provided in the authorization request
authorization_code: A short-lived, single-use code for token exchange
state: The same state value from the original request (CSRF protection)

Example values:

http://127.0.0.1:PORT/oauth/callback?code=ABC123&state=xyz
https://{region}.signin.aws.amazon.com/v1/sessions/confirmation?code=DEF456&state=abc

Errors

For information about the errors that are common to all actions, see Common Error Types.

BadRequestException

The request is invalid. Used for OAuth 2.0 request validation errors such as missing required parameters, invalid parameter values, malformed PKCE parameters, or invalid scope values.

HTTP Status Code: 400

InternalServerException

The request processing has failed because of an unknown error, exception or failure with an internal server.

HTTP Status Code: 500

TooManyRequestsError

Indicates that the principal has exceeded the limit of requests to this API operation.

HTTP Status Code: 429