---
title: Sessions
description: Represents Sessions that can queried via a REST interface.
component: pingam
version: 8.1
page_id: pingam:entity-reference:sec-amster-entity-sessions
canonical_url: https://docs.pingidentity.com/pingam/8.1/entity-reference/sec-amster-entity-sessions.html
section_ids:
  sec-amster-entity-sessions-realm-ops: Realm Operations
  sec-amster-entity-sessions-realm-ops-getsessioninfo: getSessionInfo
  sec-amster-entity-sessions-realm-ops-getsessioninfoandresetidletime: getSessionInfoAndResetIdleTime
  sec-amster-entity-sessions-realm-ops-getsessionproperties: getSessionProperties
  sec-amster-entity-sessions-realm-ops-logout: logout
  sec-amster-entity-sessions-realm-ops-logoutbyhandle: logoutByHandle
  sec-amster-entity-sessions-realm-ops-logoutbyuser: logoutByUser
  sec-amster-entity-sessions-realm-ops-query: query
  sec-amster-entity-sessions-realm-ops-refresh: refresh
  sec-amster-entity-sessions-realm-ops-updatesessionproperties: updateSessionProperties
  sec-amster-entity-sessions-realm-ops-validate: validate
---

# Sessions

## Realm Operations

Represents Sessions that can queried via a REST interface.

Resource path:

```
/sessions
```

Resource version: `5.1`

### getSessionInfo

It reads and returns the information about the requested session.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName getSessionInfo
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```

### getSessionInfoAndResetIdleTime

It reads and returns the information about the requested session. It also resets the session idle time.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName getSessionInfoAndResetIdleTime
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```

### getSessionProperties

It reads and returns all of the allowlisted properties for the requested session.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName getSessionProperties
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```

### logout

It logs out from OpenAM

**Usage**

```
am> action Sessions --realm Realm --body body --actionName logout
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```

### logoutByHandle

It logs out sessions based on the provided session handles.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName logoutByHandle
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Logout By Handle request",
    "type" : "object",
    "title" : "Logout By Handle request",
    "properties" : {
      "sessionHandles" : {
        "title" : "Session handles",
        "description" : "The array of session handles that needs to be invalidated.",
        "type" : "array",
        "items" : {
          "type" : "string"
        }
      }
    },
    "required" : [ "sessionHandles" ]
  }
  ```

### logoutByUser

No yet implemented, it will log out sessions based on the provided username and realm.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName logoutByUser
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Logout By User request [not functional yet]",
    "type" : "object",
    "title" : "Logout By User request [not functional yet]",
    "properties" : {
      "username" : {
        "title" : "Username",
        "description" : "The username to identify the user whose sessions should be invalidated.",
        "type" : "string"
      }
    },
    "required" : [ "username" ]
  }
  ```

### query

It queries all sessions using the provided query filter.

**Usage**

```
am> query Sessions --realm Realm --filter filter
```

**Parameters**

* *\--filter*

  A CREST formatted query filter, where "true" will query all. Fields that can be queried: \[username, realm]

### refresh

Suggests to OpenAM that it should refresh this session (update it's latest access time and reset its idleTime to 0). This will only be obeyed if the time between the session's previous latest access time and now is greater than the value configured for the server's Latest Access Time Update Frequency setting, which defaults to 60 seconds.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName refresh
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```

### updateSessionProperties

It updates and returns all of the allowlisted properties for the requested session.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName updateSessionProperties
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```

### validate

It checks whether the specified SSO Token Id is valid or not. If there is any problem getting or validating the token which causes an exception, the JSON response will be false. In addition, if the token is expired then the JSON response will be set to false. Otherwise it will be set to true.

**Usage**

```
am> action Sessions --realm Realm --body body --actionName validate
```

**Parameters**

* *\--body*

  The resource in JSON format, described by the following JSON schema:

  ```json
  {
    "$schema" : "http://json-schema.org/draft-04/schema#",
    "description" : "Action request",
    "title" : "Action request",
    "type" : "object",
    "properties" : {
      "tokenId" : {
        "title" : "The tokenId",
        "description" : "The tokenId of the user you request information for",
        "type" : "string"
      }
    },
    "required" : [ "tokenId" ]
  }
  ```