SignInService / Client / introspect_oauth2_token_with_iam

introspect_oauth2_token_with_iam

SignInService.Client.introspect_oauth2_token_with_iam(**kwargs)

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.

See also: AWS API Documentation

Request Syntax

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

  • token (string) –

    [REQUIRED]

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

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

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. 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 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).

    • 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) –

      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.

    • aud (string) –

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

    • 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 during Human OAuth flow. Only present for refresh token introspection.

Exceptions