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

IntrospectOAuth2TokenWithIAM

Inspects the metadata and active state of an OAuth 2.0 access token or refresh token.

Implements RFC 7662 (OAuth 2.0 Token Introspection) over a SigV4-authenticated endpoint. Returns the claims associated with a token issued by AWS Sign-In.

When the supplied token is unknown, expired, revoked, malformed, or owned by a different account, the response contains only {"active": false} with all other claims omitted.

Request Syntax


POST /v1/introspect?x-amz-client-auth-method=iam HTTP/1.1
Content-type: application/json

{
   "token": "string",
   "token_type_hint": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

token

The access token or refresh token issued by AWS Sign-In.

Type: String

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

Pattern: ASO[AR][A-Za-z0-9+/=_\-]+

Required: Yes

token_type_hint

An optional hint about the type of the token submitted for introspection, as defined in RFC 7662 §2.1. The server checks both token types regardless of the hint. Allowed values: access_token, refresh_token.

Type: String

Pattern: (access_token|refresh_token)

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "account_id": "string",
   "active": boolean,
   "aud": "string",
   "client_id": "string",
   "exp": number,
   "iat": number,
   "iss": "string",
   "jti": "string",
   "nbf": number,
   "resource": "string",
   "signin_session": "string",
   "sub": "string",
   "token_type": "string",
   "user_id": "string"
}

Response Elements

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

The following data is returned in JSON format by the service.

account_id

12-digit AWS account ID of the token's subject principal.

Type: String

Pattern: [0-9]{12}

active

Indicates whether the token is currently active. Returns true only when the token is valid, has not expired, has not been revoked, and belongs to the caller's account.

Type: Boolean

aud

The OAuth resource the token is scoped to. Omitted for refresh tokens.

Example: aws-mcp.amazonaws.com.

Type: String

client_id

Client identifier for the OAuth 2.0 client that requested the token.

Type: String

exp

Token expiration time as a NumericDate (Unix epoch seconds).

Type: Long

iat

Token issuance time as a NumericDate (Unix epoch seconds).

Type: Long

iss

Issuer of the token. Always signin.amazonaws.com for AWS Sign-In.

Type: String

jti

Unique identifier for the token.

Type: String

nbf

Token "not before" time as a NumericDate (Unix epoch seconds).

Type: Long

resource

The OAuth resource the token is scoped to. Only present for refresh token introspection.

Type: String

signin_session

AWS Sign-In session ARN bound to the token, of the form arn:aws:signin:{region}:{account}:session/{uuid}.

Type: String

sub

The IAM principal Amazon Resource Name (ARN). For assumed-role sessions, this is the session ARN.

Type: String

token_type

Indicates which kind of token was introspected. One of access_token or refresh_token.

Type: String

Pattern: (access_token|refresh_token)

user_id

User identifier matching the UserId field from sts:GetCallerIdentity for the token's subject principal.

Type: String

Errors

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

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400

InternalServerException

The request failed because of an internal server error.

HTTP Status Code: 500

TooManyRequestsError

The request failed because you exceeded the request rate limit for this operation.

HTTP Status Code: 429

ValidationException

The request failed because it contains a malformed, missing, or invalid parameter.

HTTP Status Code: 400