Skip to content

Signin  >  Operations  >  introspect_o_auth2_token_with_iam

introspect_o_auth2_token_with_iam

Operation

introspect_o_auth2_token_with_iam async 

introspect_o_auth2_token_with_iam(input: IntrospectOAuth2TokenWithIAMInput, plugins: list[Plugin] | None = None) -> IntrospectOAuth2TokenWithIAMOutput

Grants permission to inspect the metadata and state of an OAuth 2.0 access token or refresh token Implements RFC 7662 OAuth 2.0 Token Introspection over a SigV4-authenticated endpoint. Inspects the metadata of an access_token or refresh_token issued by AWS Sign-In and returns the claims associated with it. Inactive token semantics (RFC 7662 §2.2): when the supplied token is unknown, expired, revoked, malformed, or owned by a different account, the response body is exactly { "active": false } with all other claims omitted.

Parameters:

Name Type Description Default
input IntrospectOAuth2TokenWithIAMInput

An instance of IntrospectOAuth2TokenWithIAMInput.

 required
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

 None

Returns:

Type Description
IntrospectOAuth2TokenWithIAMOutput

An instance of IntrospectOAuth2TokenWithIAMOutput.

Input

IntrospectOAuth2TokenWithIAMInput dataclass

Input structure for IntrospectOAuth2TokenWithIAM operation RFC 7662 §2.1 introspection request. Contains the token to inspect and an optional hint about the token's type.

Attributes

token class-attribute instance-attribute 
token: str | None = field(repr=False, default=None)

The string value of the token to introspect. May be either an access_token or a refresh_token issued by AWS Sign-In.

token_type_hint class-attribute instance-attribute 
token_type_hint: str | None = None

Optional hint about the type of the token submitted for introspection. The server uses this hint to optimize lookup, but still falls back to the other token type on miss. Allowed values: access_token, refresh_token.

Output

IntrospectOAuth2TokenWithIAMOutput dataclass

Output structure for IntrospectOAuth2TokenWithIAM operation RFC 7662 §2.2 introspection response. Only active is required; all other claims are omitted when the token is inactive.

Attributes

account_id class-attribute instance-attribute 
account_id: str | None = None

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

active instance-attribute 
active: bool

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

aud class-attribute instance-attribute 
aud: str | None = None

Audience of the token: the OAuth resource the token is scoped to (for example, "aws-mcp.amazonaws.com"). Omitted for refresh tokens.

client_id class-attribute instance-attribute 
client_id: str | None = None

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

exp class-attribute instance-attribute 
exp: int | None = None

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

iat class-attribute instance-attribute 
iat: int | None = None

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

iss class-attribute instance-attribute 
iss: str | None = None

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

jti class-attribute instance-attribute 
jti: str | None = None

Unique identifier for the token.

nbf class-attribute instance-attribute 
nbf: int | None = None

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

resource class-attribute instance-attribute 
resource: str | None = None

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

response_metadata class-attribute instance-attribute 
response_metadata: ResponseMetadata = field(default=EMPTY_RESPONSE_METADATA, repr=False, compare=False)

Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.

signin_session class-attribute instance-attribute 
signin_session: str | None = None

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

sub class-attribute instance-attribute 
sub: str | None = None

Subject of the token: the IAM principal ARN. For assumed-role sessions, this is the session ARN (matches sts:GetCallerIdentity's Arn field), e.g. arn:aws:sts::123456789012:assumed-role/MyRole/session-name.

token_type class-attribute instance-attribute 
token_type: str | None = None

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

user_id class-attribute instance-attribute 
user_id: str | None = None

User identifier matching sts:GetCallerIdentity's UserId field for the token's subject principal (e.g. "AIDAEXAMPLE" for an IAM user, or "AROAEXAMPLE:session-name" for an assumed role).