Sessions

The sessions resource provides access to create and manage sessions.

For most apps, use Decode a session token instead of Get a session. It is much faster as it uses cryptographic signatures instead of an API call.

When using the Session APIs, please consider using Memcache, Valkey, or similar and make sure expiration times are staggered. Due to the nature of sessions, it is surprisingly easy to trigger API rate limits due to either total request volume or thundering herds.

Fields

Field	Value	Req/Default	Notes
`id`	id	Auto-generated	Session ID. Starts with “kss_”. Example: `kss_0v1zUpWdE4IiFc2w5ynShf`
`client_app_id`	client_app_id		Associated OAuth2 Client App.
`created_at`	time_t	Auto-generated	Start time of session.
`expires_at`	time_t	Auto-generated	Expiration time of session.
`token`	string	Auto-generated	Full login (JWT) token.
`user_id`	user_id	Required
`request`	hash		Hash of request attributes to add to Event. See notes.

Required permissions

Method	Permissions
List, Get	read
Create, Delete	write

List sessions for a user

List all active sessions belonging to a user.

Parameters

Param	Value	Default
`user_id`	id		Filter by user_id
`sort`	`id`	`id`	Equivalent to created_at.
`direction`	`asc`, `desc`	`asc`

Request

Example

GET /v2/sessions?user_id=usr_0v9hKVEVrWq5y7whHzSVgh

var resp = await authrocket.sessions.all({user_id: "usr_0v9hKVEVrWq5y7whHzSVgh"})

$res = $authrocket->sessions->all(["user_id" => "usr_0v9hKVEVrWq5y7whHzSVgh"]);

AuthRocket::Session.all user_id: "usr_0v9hKVEVrWq5y7whHzSVgh"

Response

Example

Status: 200

{
  "collection": [
    {
      "client_app_id": null,
      "created_at": 1735689600.0,
      "expires_at": 1735776000,
      "id": "kss_sample123456",
      "object": "session",
      "request": {
        "client": "Firefox/3141.5",
        "ip": "10.0.0.1"
      },
      "user_id": "usr_sample123456"
    }
  ],
  "more_results": false
}

// console.log(resp.results)
[
  {
    client_app_id: null,
    created_at: 1735689600.0,
    expires_at: 1735776000,
    id: "kss_sample123456",
    object: "session",
    request: {
      client: "Firefox/3141.5",
      ip: "10.0.0.1"
    },
    user_id: "usr_sample123456"
  }
]

// var_dump($res->results);
array(1) {
  [0]=> 
    array(7) {
      ["client_app_id"]=> NULL
      ["created_at"]=> float(1735689600.0)
      ["expires_at"]=> int(1735776000)
      ["id"]=> string(16) "kss_sample123456"
      ["object"]=> string(7) "session"
      ["request"]=> 
        array(2) {
          ["client"]=> string(14) "Firefox/3141.5"
          ["ip"]=> string(8) "10.0.0.1"
        }
      ["user_id"]=> string(16) "usr_sample123456"
    }
}

[AuthRocket::Session(
  client_app_id: nil,
  created_at: 2025-01-01 00:00:00 UTC,
  expires_at: 2025-01-02 00:00:00 UTC,
  id: "kss_sample123456",
  request: {"client"=>"Firefox/3141.5", "ip"=>"10.0.0.1"},
  user_id: "usr_sample123456"
 )
]

Get a session

Retrieve an active session by the session ID.

Associated user’s state must be active.

Parameters

Param	Value	Default
`expand`	`memberships`		See below.
`org_id`	org_id		Include only this org_id in JWT and memberships (if expanded).

expand

memberships - Include membership and org details in the response, for active orgs only.

org_id

If org_id is present, JWT will include that single Membership/Org (if found), regardless of Realm.jwt_scopes. If expanding memberships, the expansion will also include only that one org_id.

Request

Example

GET /v2/sessions/kss_sample123456

var resp = await authrocket.sessions.find("kss_sample123456")

$res = $authrocket->sessions->find("kss_sample123456");

session = AuthRocket::Session.find "kss_sample123456"

Response

Example

Status: 200

{
  "client_app_id": null,
  "created_at": 1735689600.0,
  "expires_at": 1735776000,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "Firefox/3141.5",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "created_at": 1735689600.0,
    "credentials": [
      {
        "credential_type": "password",
        "id": "crd_sample123456",
        "object": "credential"
      }
    ],
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": null,
    "last_name": "Crockett",
    "locale": null,
    "membership_count": 0,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

Status: 404 if session not found, user not found, or user not active.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1735689600.0,
  expires_at: 1735776000,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "Firefox/3141.5",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    created_at: 1735689600.0,
    credentials: [
      {
        credential_type: "password",
        id: "crd_sample123456",
        object: "credential"
      }
    ],
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: null,
    last_name: "Crockett",
    locale: null,
    membership_count: 0,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1735689600.0)
  ["expires_at"]=> int(1735776000)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(14) "Firefox/3141.5"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(18) {
      ["created_at"]=> float(1735689600.0)
      ["credentials"]=> 
        array(1) {
          [0]=> 
            array(3) {
              ["credential_type"]=> string(8) "password"
              ["id"]=> string(16) "crd_sample123456"
              ["object"]=> string(10) "credential"
            }
        }
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> NULL
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["membership_count"]=> int(0)
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2025-01-01 00:00:00 UTC,
 expires_at: 2025-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"Firefox/3141.5", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: 
  AuthRocket::User(
   created_at: 2025-01-01 00:00:00 UTC,
   credentials: 
    [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
     )],
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: nil,
   last_name: "Crockett",
   locale: nil,
   membership_count: 0,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

Decode a session token

All official AuthRocket SDKs include a method to decode an existing JWT token without making an API call. This is much faster than executing API calls and is recommended.

Tokens are verified for forgery and expiration time.

Request

Example

var resp = await authrocket.sessions.fromToken("session-token")

$res = $authrocket->sessions->fromToken("session-token");

session = AuthRocket::Session.from_token "session-token"

Response

Example

On success, returns a Session object with nested User and usually one set of Membership+Org objects.

// console.log(resp.results)
{
  created_at: 1735689600,
  expires_at: 1735711200,
  id: "kss_sample123456",
  object: "session",
  token: "original-token",
  user: {
    custom: {},
    email: "davy@example.com",
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_name: "Crockett",
    memberships: [
      {
        id: "mb_sample123456",
        object: "membership",
        org: {
          custom: {},
          id: "org_sample123456",
          name: "Widgets Inc",
          object: "org",
          realm_id: "rl_sample123456",
          reference: null
        },
        org_id: "org_sample123456",
        permissions: [
          "forum:admin"
        ],
        user_id: "usr_sample123456"
      }
    ],
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    username: "davy"
  },
  user_id: "usr_sample123456"
}

Note: returned objects contain only the attributes available inside the JWT token and will not be complete. If you need the additional attributes, use Get a Session with the session id.

If token is invalid or expired, returns null.

On success, returns a Session array with nested User and usually one set of Membership+Org arrays.

// var_dump($res->fields);
array(7) {
  ["created_at"]=> int(1735689600)
  ["expires_at"]=> int(1735711200)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["token"]=> string(14) "original-token"
  ["user"]=> 
    array(12) {
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_name"]=> string(8) "Crockett"
      ["memberships"]=> 
        array(1) {
          [0]=> 
            array(6) {
              ["id"]=> string(15) "mb_sample123456"
              ["object"]=> string(10) "membership"
              ["org"]=> 
                array(6) {
                  ["custom"]=> array(0) {}
                  ["id"]=> string(16) "org_sample123456"
                  ["name"]=> string(11) "Widgets Inc"
                  ["object"]=> string(3) "org"
                  ["realm_id"]=> string(15) "rl_sample123456"
                  ["reference"]=> NULL
                }
              ["org_id"]=> string(16) "org_sample123456"
              ["permissions"]=> 
                array(1) {
                  [0]=> string(11) "forum:admin"
                }
              ["user_id"]=> string(16) "usr_sample123456"
            }
        }
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

Note: returned objects contain only the attributes available inside the JWT token and will not be complete. If you need the additional attributes, use Get a Session with the session id.

If token is invalid or expired, returns null.

On success, returns a Session object, with nested User and usually one set Membership+Org objects.

AuthRocket::Session(
 created_at: 2025-01-01 00:00:00 UTC,
 expires_at: 2025-01-01 06:00:00 UTC,
 id: "kss_sample123456",
 token: "original-token",
 user: 
  AuthRocket::User(
   custom: {},
   email: "davy@example.com",
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_name: "Crockett",
   memberships: 
    [AuthRocket::Membership(
      id: "mb_sample123456",
      org: 
       AuthRocket::Org(
        custom: {},
        id: "org_sample123456",
        name: "Widgets Inc",
        realm_id: "rl_sample123456",
        reference: nil
       ),
      org_id: "org_sample123456",
      permissions: ["forum:admin"],
      user_id: "usr_sample123456"
     )],
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

Note: returned objects contain only the attributes available inside the JWT token and will not be complete. If you need the additional attributes, use #reload. For example:

user = session.user
user.updated_at # => nil
user.reload
user.updated_at # => #<Time ...>
user.memberships(reload: true)

If token is invalid or expired, returns nil.

Create a session

Create a new session for a user.

This does not authenticate or otherwise verify a user. The normal way to create a session for a user is by using Authenticate Using a Password.

This method is useful for establishing a session for a newly created user (instead of requiring them to immediately authenticate).

It is also useful if you have previously authenticated the user by other means or for impersonating a user.

Request

Example

POST /v2/sessions

{
  "request": {
    "client": "MyApp/v1.0.0",
    "ip": "10.0.0.1"
  },
  "session": {
    "user_id": "usr_sample123456"
  }
}

var resp = await authrocket.sessions.create({
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  request: {client: "MyApp/v1.0.0", ip: "10.0.0.1"}
})

$res = $authrocket->sessions->create([
  "user_id" => "usr_0v1zUpWdE4IiFc2w5ynShf",
  "request" => ["client" => "MyApp/v1.0.0", "ip" => "10.0.0.1"]
]);

session = AuthRocket::Session.create(
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  request: {client: "MyApp/v1.0.0", ip: "10.0.0.1"}
)

Response

Example

On success, status 201 with the new Session.

{
  "client_app_id": null,
  "created_at": 1735689600.0,
  "expires_at": 1735776000,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "MyApp/v1.0.0",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "created_at": 1735689600.0,
    "credentials": [
      {
        "credential_type": "password",
        "id": "crd_sample123456",
        "object": "credential"
      }
    ],
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": null,
    "last_name": "Crockett",
    "locale": null,
    "membership_count": 0,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.
If user not found or not active, status 404.

On success, returns an object with the new Session.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1735689600.0,
  expires_at: 1735776000,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "MyApp/v1.0.0",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    created_at: 1735689600.0,
    credentials: [
      {
        credential_type: "password",
        id: "crd_sample123456",
        object: "credential"
      }
    ],
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: null,
    last_name: "Crockett",
    locale: null,
    membership_count: 0,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.
If user not found or not active, throws an exception.

On success, returns an object with the new Session.

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1735689600.0)
  ["expires_at"]=> int(1735776000)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(12) "MyApp/v1.0.0"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(18) {
      ["created_at"]=> float(1735689600.0)
      ["credentials"]=> 
        array(1) {
          [0]=> 
            array(3) {
              ["credential_type"]=> string(8) "password"
              ["id"]=> string(16) "crd_sample123456"
              ["object"]=> string(10) "credential"
            }
        }
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> NULL
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["membership_count"]=> int(0)
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.
If user not found or not active, throws an exception.

On success, returns an object with the new Session.

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2025-01-01 00:00:00 UTC,
 expires_at: 2025-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"MyApp/v1.0.0", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: 
  AuthRocket::User(
   created_at: 2025-01-01 00:00:00 UTC,
   credentials: 
    [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
     )],
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: nil,
   last_name: "Crockett",
   locale: nil,
   membership_count: 0,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

On failure, returns an object with a standard error response.
If user not found or not active, throws an exception.

Events

Does not trigger any events.

Delete a session

Deletes a session.

Will return success if user or session already deleted, so safe to use in all normal circumstances.

Request

Example

DELETE /v2/sessions/kss_sample123456

var resp = await authrocket.sessions.delete("kss_sample123456")

$res = $authrocket->sessions->delete("kss_sample123456");

AuthRocket::Session.delete "kss_sample123456"

Response

Example

On success, status 204 with an empty response.

On success, returns an object with no errors.

Events

Does not trigger any events.

Sessions

Fields

Required permissions

List sessions for a user

Parameters

Request

Example

Response

Example

Get a session

Parameters

expand

org_id

Request

Example

Response

Example

Decode a session token

Request

Example

Response

Example

Create a session

Request

Example

Response

Example

Events

Delete a session

Request

Example

Response

Example

Events

Contents