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:
The operation behavior is determined by the grant_type parameter in the request body:
Authorization Code Flow (NOT Idempotent):
Token Refresh Flow (Idempotent):
Authentication and authorization:
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.
", "auth":["smithy.api#noAuth"], "authtype":"none" } }, "shapes":{ "AccessDeniedException":{ "type":"structure", "required":[ "error", "message" ], "members":{ "error":{ "shape":"OAuth2ErrorCode", "documentation":"OAuth 2.0 error code indicating the specific type of access denial Can be TOKEN_EXPIRED, AUTHCODE_EXPIRED, USER_CREDENTIALS_CHANGED, or INSUFFICIENT_PERMISSIONS
" }, "message":{ "shape":"String", "documentation":"Detailed message explaining the access denial Provides specific information about why access was denied
" } }, "documentation":"Error thrown for access denied scenarios with flexible HTTP status mapping
Runtime HTTP Status Code Mapping:
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.
", "exception":true }, "AccessToken":{ "type":"structure", "required":[ "accessKeyId", "secretAccessKey", "sessionToken" ], "members":{ "accessKeyId":{ "shape":"String", "documentation":"AWS access key ID for temporary credentials
", "locationName":"accessKeyId" }, "secretAccessKey":{ "shape":"String", "documentation":"AWS secret access key for temporary credentials
", "locationName":"secretAccessKey" }, "sessionToken":{ "shape":"String", "documentation":"AWS session token for temporary credentials
", "locationName":"sessionToken" } }, "documentation":"AWS credentials structure containing temporary access credentials
The scoped-down, 15 minute duration AWS credentials. Scoping down will be based on CLI policy (CLI team needs to create it). Similar to cloud shell implementation.
", "sensitive":true }, "AuthorizationCode":{ "type":"string", "documentation":"Authorization code received from AWS Sign-In /v1/authorize endpoint
The authorization code received from AWS Sign-In from /v1/authorize. Used in auth code redemption flow only.
", "max":512, "min":1 }, "ClientId":{ "type":"string", "documentation":"Client identifier pattern for AWS Sign-In devtools clients
The ARN used by client as part of Sign-In onboarding. Expected values:
This will be finalized after consulting with UX as this is visible to end customer.
", "pattern":"arn:aws:signin:::devtools/(cross-device|same-device)" }, "CodeVerifier":{ "type":"string", "documentation":"PKCE code verifier for OAuth 2.0 security
PKCE code verifier to prove possession of the original code challenge. Used to prevent authorization code interception attacks in public clients. Must be 43-128 characters using unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
", "max":128, "min":43, "pattern":"[A-Za-z0-9\\-._~]+" }, "CreateOAuth2TokenRequest":{ "type":"structure", "required":["tokenInput"], "members":{ "tokenInput":{ "shape":"CreateOAuth2TokenRequestBody", "documentation":"Flattened token operation inputs The specific operation is determined by grant_type in the request body
" } }, "documentation":"Input structure for CreateOAuth2Token operation
Contains flattened token operation inputs for both authorization code and refresh token flows. The operation type is determined by the grant_type parameter in the request body.
", "payload":"tokenInput" }, "CreateOAuth2TokenRequestBody":{ "type":"structure", "required":[ "clientId", "grantType" ], "members":{ "clientId":{ "shape":"ClientId", "documentation":"The client identifier (ARN) used during Sign-In onboarding Required for both authorization code and refresh token flows
", "locationName":"clientId" }, "grantType":{ "shape":"GrantType", "documentation":"OAuth 2.0 grant type - determines which flow is used Must be "authorization_code" or "refresh_token"
", "locationName":"grantType" }, "code":{ "shape":"AuthorizationCode", "documentation":"The authorization code received from /v1/authorize Required only when grant_type=authorization_code
" }, "redirectUri":{ "shape":"RedirectUri", "documentation":"The redirect URI that must match the original authorization request Required only when grant_type=authorization_code
", "locationName":"redirectUri" }, "codeVerifier":{ "shape":"CodeVerifier", "documentation":"PKCE code verifier to prove possession of the original code challenge Required only when grant_type=authorization_code
", "locationName":"codeVerifier" }, "refreshToken":{ "shape":"RefreshToken", "documentation":"The refresh token returned from auth_code redemption Required only when grant_type=refresh_token
", "locationName":"refreshToken" } }, "documentation":"Request body payload for CreateOAuth2Token operation
The operation type is determined by the grant_type parameter:
Flattened token operation outputs The specific response fields depend on the grant_type used in the request
" } }, "documentation":"Output structure for CreateOAuth2Token operation
Contains flattened token operation outputs for both authorization code and refresh token flows. The response content depends on the grant_type from the original request.
", "payload":"tokenOutput" }, "CreateOAuth2TokenResponseBody":{ "type":"structure", "required":[ "accessToken", "tokenType", "expiresIn", "refreshToken" ], "members":{ "accessToken":{ "shape":"AccessToken", "documentation":"Scoped-down AWS credentials (15 minute duration) Present for both authorization code redemption and token refresh
", "locationName":"accessToken" }, "tokenType":{ "shape":"TokenType", "documentation":"Token type indicating this is AWS SigV4 credentials Value is "aws_sigv4" for both flows
", "locationName":"tokenType" }, "expiresIn":{ "shape":"ExpiresIn", "documentation":"Time to expiry in seconds (maximum 900) Present for both authorization code redemption and token refresh
", "locationName":"expiresIn" }, "refreshToken":{ "shape":"RefreshToken", "documentation":"Encrypted refresh token with cnf.jkt (SHA-256 thumbprint of presented jwk) Always present in responses (required for both flows)
", "locationName":"refreshToken" }, "idToken":{ "shape":"IdToken", "documentation":"ID token containing user identity information Present only in authorization code redemption response (grant_type=authorization_code) Not included in token refresh responses
", "locationName":"idToken" } }, "documentation":"Response body payload for CreateOAuth2Token operation
The response content depends on the grant_type from the request:
Time to expiry in seconds
The time to expiry in seconds, for these purposes will be at most 900 (15 minutes).
", "box":true, "max":900, "min":1 }, "GrantType":{ "type":"string", "documentation":"OAuth 2.0 grant type parameter
For auth code redemption: Must be "authorization_code" For token refresh: Must be "refresh_token"
Based on client_id & grant_type, authn/authz is skipped for CLI endpoints.
", "pattern":"(authorization_code|refresh_token)" }, "IdToken":{ "type":"string", "documentation":"ID token containing user identity information
Encoded JWT token containing user identity claims and authentication context. Returned only in authorization code redemption responses (grant_type=authorization_code). Contains user identity information such as ARN and other identity claims.
", "max":4096, "min":1 }, "InternalServerException":{ "type":"structure", "required":[ "error", "message" ], "members":{ "error":{ "shape":"OAuth2ErrorCode", "documentation":"OAuth 2.0 error code indicating server error Will be SERVER_ERROR for internal server errors
" }, "message":{ "shape":"String", "documentation":"Detailed message explaining the server error May include error details for debugging purposes
" } }, "documentation":"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.
", "error":{"httpStatusCode":500}, "exception":true, "fault":true }, "OAuth2ErrorCode":{ "type":"string", "documentation":"OAuth 2.0 error codes returned by the server
Standard OAuth 2.0 error codes used in error responses to indicate the specific type of error that occurred during token operations.
", "enum":[ "TOKEN_EXPIRED", "USER_CREDENTIALS_CHANGED", "INSUFFICIENT_PERMISSIONS", "AUTHCODE_EXPIRED", "server_error", "INVALID_REQUEST" ] }, "RedirectUri":{ "type":"string", "documentation":"Redirect URI for OAuth 2.0 flow validation
The same redirect URI used in the authorization request. This must match exactly what was sent in the original authorization request for security validation.
", "max":2048, "min":1 }, "RefreshToken":{ "type":"string", "documentation":"Encrypted refresh token with cnf.jkt
This is the encrypted refresh token returned from auth code redemption. The token content includes cnf.jkt (SHA-256 thumbprint of the presented jwk). Used in subsequent token refresh requests.
", "max":2048, "min":1, "sensitive":true }, "String":{"type":"string"}, "TokenType":{ "type":"string", "documentation":"Token type parameter indicating credential usage
A parameter which indicates to the client how the token must be used. Value is "aws_sigv4" (instead of typical "Bearer" for other OAuth systems) to indicate that the client must de-serialize the token and use it to generate a signature.
", "pattern":"aws_sigv4" }, "TooManyRequestsError":{ "type":"structure", "required":[ "error", "message" ], "members":{ "error":{ "shape":"OAuth2ErrorCode", "documentation":"OAuth 2.0 error code indicating the specific type of error Will be INVALID_REQUEST for rate limiting scenarios
" }, "message":{ "shape":"String", "documentation":"Detailed message about the rate limiting May include retry-after information or rate limit details
" } }, "documentation":"Error thrown when rate limit is exceeded
HTTP Status Code: 429 Too Many Requests
Possible OAuth2ErrorCode values:
Possible causes:
OAuth 2.0 error code indicating validation failure Will be INVALID_REQUEST for validation errors
" }, "message":{ "shape":"String", "documentation":"Detailed message explaining the validation failure Provides specific information about which validation failed
" } }, "documentation":"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.
", "error":{ "httpStatusCode":400, "senderFault":true }, "exception":true } }, "documentation":"AWS Sign-In manages authentication for AWS services. This service provides secure authentication flows for accessing AWS resources from the console and developer tools.
" }