SignInService / Client / introspect_oauth2_token_with_iam

introspect_oauth2_token_with_iam

SignInService.Client.introspect_oauth2_token_with_iam(**kwargs)

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.

See also: AWS API Documentation

Request Syntax

response = client.introspect_oauth2_token_with_iam(
    token='string',
    tokenTypeHint='string'
)
Parameters:

  • token (string) –

    [REQUIRED]

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

  • tokenTypeHint (string) – 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”.

Return type:

dict

Returns:

Response Syntax

{
    'active': True|False,
    'clientId': 'string',
    'userId': 'string',
    'tokenType': 'string',
    'exp': 123,
    'iat': 123,
    'nbf': 123,
    'sub': 'string',
    'aud': 'string',
    'iss': 'string',
    'jti': 'string',
    'accountId': 'string',
    'signinSession': 'string',
    'resource': 'string'
}

Response Structure

  • (dict) –

    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.

    • active (boolean) –

      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.

    • clientId (string) –

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

    • userId (string) –

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

    • tokenType (string) –

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

    • exp (integer) –

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

    • iat (integer) –

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

    • nbf (integer) –

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

    • sub (string) –

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

    • aud (string) –

      The OAuth resource the token is scoped to. Omitted for refresh tokens. Example: “aws-mcp.amazonaws.com”.

    • iss (string) –

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

    • jti (string) –

      Unique identifier for the token.

    • accountId (string) –

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

    • signinSession (string) –

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

    • resource (string) –

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

Exceptions