2026/11/11 - Amazon Cognito Identity Provider - 8 new1 updated api methods
Changes This release adds session management operations that let user pool administrators and users list and revoke active sessions, and configure session tracking, per-user session limits, and SSO session validity per app client.
Lists the active sessions for the currently signed-in user. Amazon Cognito authorizes this operation with the user's access token and returns all of the user's active sessions across every app client in the user pool, including both token sessions and SSO sessions. The IsCurrentSession field identifies the session that the calling access token belongs to. The results are eventually consistent, and new sessions are typically included within a few seconds.
See also: AWS API Documentation
Request Syntax
client.list_user_sessions(
AccessToken='string',
NextToken='string'
)
string
[REQUIRED]
A valid access token that Amazon Cognito issued to the user whose sessions you want to list. Amazon Cognito derives the user pool and username from this token.
string
A pagination token that Amazon Cognito returned in a previous response. Use this value to retrieve the next page of results if a NextToken was included in a prior response.
dict
Response Syntax
{
'Sessions': [
{
'SessionId': 'string',
'SessionType': 'TOKEN'|'SSO',
'ClientId': 'string',
'CreateDate': datetime(2015, 1, 1),
'LastActiveDate': datetime(2015, 1, 1),
'DeviceType': 'string',
'LastIPAddress': 'string',
'LastLocation': {
'City': 'string',
'Country': 'string'
},
'OriginSessionId': 'string',
'IsCurrentSession': True|False
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Sessions (list) --
A list of the user's active sessions. Each element describes one token session or SSO session.
(dict) --
Describes an active user session. Amazon Cognito returns this type in the responses of ListUserSessions and AdminListUserSessions, for both token sessions and SSO sessions.
SessionId (string) --
The unique identifier for the session. This is a 28-character string of lowercase letters and digits, prefixed with tkn for a token session or sso for an SSO session.
SessionType (string) --
The type of the session. Valid values are TOKEN and SSO.
ClientId (string) --
The ID of the app client that the session belongs to.
CreateDate (datetime) --
The date and time when the session was created.
LastActiveDate (datetime) --
The date and time of the most recent activity on the session. For a token session, this is the most recent token refresh or rotation; a new authentication creates a new token session rather than updating an existing one. For an SSO session, this is the most recent authentication, token grant, or token rotation.
DeviceType (string) --
A description of the device associated with the most recent activity on the session, derived from the parsed user agent (operating system and browser or app). Amazon Cognito overwrites this value on each sign-in, refresh, and rotation. The value can be unknown. The maximum length is 1,024 characters.
LastIPAddress (string) --
The IP address associated with the most recent activity on the session. Amazon Cognito overwrites this value on each refresh and rotation. The maximum length is 128 characters.
LastLocation (dict) --
The geographic location of the most recent activity on the session, derived from the IP address.
City (string) --
The city of the most recent activity on the session, derived from the IP address. This value can be null if geo-IP resolution fails. The maximum length is 256 characters.
Country (string) --
The country of the most recent activity on the session, derived from the IP address and returned in English (for example, United States). This is a country name as returned by the geo-IP database, not an ISO country code, and can be unknown if geo-IP resolution fails.
OriginSessionId (string) --
For a token session, the ID of the SSO session that the token session originated from. This value is null for sessions that were initiated through the API and didn't come through an SSO session. Amazon Cognito returns this value for token sessions only.
IsCurrentSession (boolean) --
Specifies whether this session matches the access token supplied in the request. This value is always false for the AdminListUserSessions operation, which doesn't take an access token.
NextToken (string) --
The pagination token to use in a subsequent request to retrieve the next page of results.
Lists the active sessions for a specified user as an administrator. The response includes both token sessions and SSO sessions. Only active sessions are returned; revoked and expired sessions aren't included. Amazon Cognito returns all of a user's sessions in a single page of up to 125 sessions. The results are eventually consistent, and new sessions are typically included within a few seconds.
See also: AWS API Documentation
Request Syntax
client.admin_list_user_sessions(
UserPoolId='string',
Username='string',
NextToken='string'
)
string
[REQUIRED]
The ID of the user pool that contains the user.
string
[REQUIRED]
The username of the user whose sessions you want to list.
string
A pagination token that Amazon Cognito returned in a previous response. Use this value to retrieve the next page of results if a NextToken was included in a prior response.
dict
Response Syntax
{
'Sessions': [
{
'SessionId': 'string',
'SessionType': 'TOKEN'|'SSO',
'ClientId': 'string',
'CreateDate': datetime(2015, 1, 1),
'LastActiveDate': datetime(2015, 1, 1),
'DeviceType': 'string',
'LastIPAddress': 'string',
'LastLocation': {
'City': 'string',
'Country': 'string'
},
'OriginSessionId': 'string',
'IsCurrentSession': True|False
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Sessions (list) --
A list of the user's active sessions. Each element describes one token session or SSO session.
(dict) --
Describes an active user session. Amazon Cognito returns this type in the responses of ListUserSessions and AdminListUserSessions, for both token sessions and SSO sessions.
SessionId (string) --
The unique identifier for the session. This is a 28-character string of lowercase letters and digits, prefixed with tkn for a token session or sso for an SSO session.
SessionType (string) --
The type of the session. Valid values are TOKEN and SSO.
ClientId (string) --
The ID of the app client that the session belongs to.
CreateDate (datetime) --
The date and time when the session was created.
LastActiveDate (datetime) --
The date and time of the most recent activity on the session. For a token session, this is the most recent token refresh or rotation; a new authentication creates a new token session rather than updating an existing one. For an SSO session, this is the most recent authentication, token grant, or token rotation.
DeviceType (string) --
A description of the device associated with the most recent activity on the session, derived from the parsed user agent (operating system and browser or app). Amazon Cognito overwrites this value on each sign-in, refresh, and rotation. The value can be unknown. The maximum length is 1,024 characters.
LastIPAddress (string) --
The IP address associated with the most recent activity on the session. Amazon Cognito overwrites this value on each refresh and rotation. The maximum length is 128 characters.
LastLocation (dict) --
The geographic location of the most recent activity on the session, derived from the IP address.
City (string) --
The city of the most recent activity on the session, derived from the IP address. This value can be null if geo-IP resolution fails. The maximum length is 256 characters.
Country (string) --
The country of the most recent activity on the session, derived from the IP address and returned in English (for example, United States). This is a country name as returned by the geo-IP database, not an ISO country code, and can be unknown if geo-IP resolution fails.
OriginSessionId (string) --
For a token session, the ID of the SSO session that the token session originated from. This value is null for sessions that were initiated through the API and didn't come through an SSO session. Amazon Cognito returns this value for token sessions only.
IsCurrentSession (boolean) --
Specifies whether this session matches the access token supplied in the request. This value is always false for the AdminListUserSessions operation, which doesn't take an access token.
NextToken (string) --
The pagination token to use in a subsequent request to retrieve the next page of results.
Sets the session configuration for a user pool app client. The configurable client-level setting is the maximum validity period for silent reuse of an SSO session. This operation performs a full replacement of the client-level session configuration; every request parameter is required, and session tracking must be enabled for the user pool. The user pool must be in the Essentials or Plus tier. Otherwise, this operation returns a FeatureUnavailableInTierException.
See also: AWS API Documentation
Request Syntax
client.set_user_pool_client_session_configuration(
UserPoolId='string',
ClientId='string',
SSOSession={
'MaxValidityMinutes': 123
}
)
string
[REQUIRED]
The ID of the user pool that contains the app client.
string
[REQUIRED]
The ID of the app client that you want to configure.
dict
[REQUIRED]
The SSO session settings for the app client.
MaxValidityMinutes (integer) -- [REQUIRED]
The maximum amount of time, in minutes, that this app client silently reuses an existing SSO session, returning a new set of tokens without requiring the user to re-authenticate, measured from the user's last fresh authentication. The minimum value is 0 and the maximum value is 129600 (90 days). The default is 60. A value of 0 means that this app client never silently reuses the SSO session and always re-authenticates the user. The SSO session record and its cookie are still created regardless of this value, and other app clients in the same user pool can still reuse the session.
dict
Response Syntax
{
'UserPoolId': 'string',
'ClientId': 'string',
'SSOSession': {
'MaxValidityMinutes': 123
}
}
Response Structure
(dict) --
UserPoolId (string) --
The ID of the user pool that contains the app client.
ClientId (string) --
The ID of the app client that the session configuration was applied to.
SSOSession (dict) --
The SSO session settings that were applied to the app client.
MaxValidityMinutes (integer) --
The maximum amount of time, in minutes, that this app client silently reuses an existing SSO session, returning a new set of tokens without requiring the user to re-authenticate, measured from the user's last fresh authentication. The minimum value is 0 and the maximum value is 129600 (90 days). The default is 60. A value of 0 means that this app client never silently reuses the SSO session and always re-authenticates the user. The SSO session record and its cookie are still created regardless of this value, and other app clients in the same user pool can still reuse the session.
Revokes a specific session for the currently signed-in user. Amazon Cognito authorizes this operation with the user's access token, revokes all refresh and access tokens that are associated with the session, and deletes the session record. You can't revoke the session that the calling access token belongs to.
See also: AWS API Documentation
Request Syntax
client.revoke_user_session(
AccessToken='string',
SessionId='string',
RevokeAssociatedSessions='NONE'|'LINKED'
)
string
[REQUIRED]
A valid access token that Amazon Cognito issued to the user. Amazon Cognito uses this token to authorize the request and to identify the user.
string
[REQUIRED]
The ID of the session to revoke. This is a 28-character string of lowercase letters and digits, prefixed with tkn for a token session or sso for an SSO session. This value can't identify the caller's own current session.
string
Specifies whether to also revoke the sessions that are linked to the targeted session. NONE, the default, revokes only the targeted session. LINKED also revokes the directly linked session or sessions, interpreted relative to the type of the targeted session: revoking a token session also revokes the parent SSO session it came through, and revoking an SSO session also revokes the token sessions that came through it. The set of linked sessions is eventually consistent, so associated sessions are typically revoked within a few seconds.
dict
Response Syntax
{}
Response Structure
(dict) --
Enables or disables session tracking for a user pool, and sets the pool-wide maximum number of active token sessions that each user can have. This operation performs a full replacement of the pool-level session configuration; every request parameter is required. The user pool must be in the Essentials or Plus tier. Otherwise, this operation returns a FeatureUnavailableInTierException.
See also: AWS API Documentation
Request Syntax
client.set_user_pool_session_configuration(
UserPoolId='string',
UserSessionTracking='ENABLED'|'DISABLED',
TokenSession={
'MaxPerUser': 123
}
)
string
[REQUIRED]
The ID of the user pool where you want to configure session tracking.
string
[REQUIRED]
Specifies whether Amazon Cognito tracks sessions for users in the user pool. Set this value to ENABLED to turn on server-side session tracking, or DISABLED to turn it off. When you set this value to DISABLED while the user pool remains active, existing client-level session configurations are retained but dormant, and are reactivated when you enable tracking again.
dict
[REQUIRED]
The pool-wide token session settings to apply.
MaxPerUser (integer) -- [REQUIRED]
The maximum number of active token sessions that a user can have across the user pool. The minimum value is 1 and the maximum value is 100. The default is 20. When a user reaches this limit, the next successful authentication automatically evicts that user's least recently used token session before it creates the new session. Lowering this value doesn't evict existing sessions on its own; the user is brought back within the limit on their next sign-in.
dict
Response Syntax
{
'UserPoolId': 'string',
'UserSessionTracking': 'ENABLED'|'DISABLED',
'TokenSession': {
'MaxPerUser': 123
}
}
Response Structure
(dict) --
UserPoolId (string) --
The ID of the user pool that the session configuration was applied to.
UserSessionTracking (string) --
The session tracking setting that was applied to the user pool.
TokenSession (dict) --
The pool-wide token session settings that were applied.
MaxPerUser (integer) --
The maximum number of active token sessions that a user can have across the user pool. The minimum value is 1 and the maximum value is 100. The default is 20. When a user reaches this limit, the next successful authentication automatically evicts that user's least recently used token session before it creates the new session. Lowering this value doesn't evict existing sessions on its own; the user is brought back within the limit on their next sign-in.
Retrieves the session tracking configuration for a user pool, including whether session tracking is enabled and the pool-wide maximum number of active token sessions for each user. If you have never called SetUserPoolSessionConfiguration for the user pool, this operation returns the default values: UserSessionTracking as DISABLED and a MaxPerUser value of 20.
See also: AWS API Documentation
Request Syntax
client.get_user_pool_session_configuration(
UserPoolId='string'
)
string
[REQUIRED]
The ID of the user pool where you want to retrieve the session configuration.
dict
Response Syntax
{
'UserPoolId': 'string',
'UserSessionTracking': 'ENABLED'|'DISABLED',
'TokenSession': {
'MaxPerUser': 123
}
}
Response Structure
(dict) --
UserPoolId (string) --
The ID of the user pool that the session configuration applies to.
UserSessionTracking (string) --
Indicates whether session tracking is enabled for the user pool.
TokenSession (dict) --
The pool-wide token session settings for the user pool.
MaxPerUser (integer) --
The maximum number of active token sessions that a user can have across the user pool. The minimum value is 1 and the maximum value is 100. The default is 20. When a user reaches this limit, the next successful authentication automatically evicts that user's least recently used token session before it creates the new session. Lowering this value doesn't evict existing sessions on its own; the user is brought back within the limit on their next sign-in.
Retrieves the session configuration for a user pool app client. If you have never called SetUserPoolClientSessionConfiguration for the app client, this operation returns the default SSO session maximum validity of 60 minutes.
See also: AWS API Documentation
Request Syntax
client.get_user_pool_client_session_configuration(
UserPoolId='string',
ClientId='string'
)
string
[REQUIRED]
The ID of the user pool that contains the app client.
string
[REQUIRED]
The ID of the app client where you want to retrieve the session configuration.
dict
Response Syntax
{
'UserPoolId': 'string',
'ClientId': 'string',
'SSOSession': {
'MaxValidityMinutes': 123
}
}
Response Structure
(dict) --
UserPoolId (string) --
The ID of the user pool that contains the app client.
ClientId (string) --
The ID of the app client that the session configuration applies to.
SSOSession (dict) --
The SSO session settings for the app client.
MaxValidityMinutes (integer) --
The maximum amount of time, in minutes, that this app client silently reuses an existing SSO session, returning a new set of tokens without requiring the user to re-authenticate, measured from the user's last fresh authentication. The minimum value is 0 and the maximum value is 129600 (90 days). The default is 60. A value of 0 means that this app client never silently reuses the SSO session and always re-authenticates the user. The SSO session record and its cookie are still created regardless of this value, and other app clients in the same user pool can still reuse the session.
Revokes a specific user session as an administrator. Amazon Cognito revokes all refresh and access tokens that are associated with the session and deletes the session record. You can revoke either a token session or an SSO session, and you can optionally cascade the revocation to linked sessions.
See also: AWS API Documentation
Request Syntax
client.admin_revoke_user_session(
UserPoolId='string',
Username='string',
SessionId='string',
RevokeAssociatedSessions='NONE'|'LINKED'
)
string
[REQUIRED]
The ID of the user pool that contains the session.
string
[REQUIRED]
The username of the user who owns the session. The username must match the user associated with the SessionId, to confirm they are the intended target user.
string
[REQUIRED]
The ID of the session to revoke. This is a 28-character string of lowercase letters and digits, prefixed with tkn for a token session or sso for an SSO session.
string
Specifies whether to also revoke the sessions that are linked to the targeted session. NONE, the default, revokes only the targeted session. LINKED also revokes the directly linked session or sessions, interpreted relative to the type of the targeted session: revoking a token session also revokes the parent SSO session it came through, and revoking an SSO session also revokes the token sessions that came through it. The set of linked sessions is eventually consistent, so associated sessions are typically revoked within a few seconds.
dict
Response Syntax
{}
Response Structure
(dict) --
{'RevokeAssociatedSessions': 'NONE | LINKED'}
Revokes all of the access tokens generated by, and at the same time as, the specified refresh token. After a token is revoked, you can't use the revoked token to access Amazon Cognito user APIs, or to authorize access to your resource server.
See also: AWS API Documentation
Request Syntax
client.revoke_token(
Token='string',
ClientId='string',
ClientSecret='string',
RevokeAssociatedSessions='NONE'|'LINKED'
)
string
[REQUIRED]
The refresh token that you want to revoke.
string
[REQUIRED]
The ID of the app client where the token that you want to revoke was issued.
string
The client secret of the requested app client, if the client has a secret.
string
Specifies whether to also revoke the SSO session that is linked to the token session being revoked. NONE, the default, revokes only the token session that is associated with the refresh token. LINKED also revokes the parent SSO session that the token session came through; the other token sessions that came through that SSO session aren't revoked. LINKED has no effect when session tracking is disabled or when the token session has no parent SSO session.
dict
Response Syntax
{}
Response Structure
(dict) --