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

FieldValueReq/DefaultNotes
id id Auto-generated

Session ID. IDs start with “kss_”.
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

MethodPermissions
List, Get read
Create, Delete write

List sessions for a user

List all active sessions belonging to a user.

Parameters

ParamValueDefault
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

{ "more_results" : false,
  "collection" : [
    { "id" : "kss_0vAAjvavvCaZQd76VvFt4b",
      "user_id" : "usr_0v9hKVEVrWq5y7whHzSVgh",
      "object" : "session",
      "created_at" : 1423941493.701,
      "expires_at" : 1423963093,
      "request" : {
        "ip" : "10.0.0.1",
        "client" : "MyApp for iOS/v1.0.0"
      }
    }
  ]
}

console.log(resp.results)
[ { id: "kss_0vAAjvavvCaZQd76VvFt4b",
    user_id: "usr_0v9hKVEVrWq5y7whHzSVgh",
    object: "session",
    created_at: 1423941493.701,
    expires_at: 1423963093,
    request: {
      ip: "10.0.0.1",
      client: "MyApp for iOS/v1.0.0"
    }
  }
]
var_dump($res->results);
  array(1) {
    [0]=>
    array(6) {
      ["id"]=> string(26) "kss_0vAAjvavvCaZQd76VvFt4b"
      ["user_id"]=> string(26) "usr_0v9hKVEVrWq5y7whHzSVgh"
      ["object"]=> string(7) "session"
      ["created_at"]=> float(1423941493.701)
      ["expires_at"]=> int(1423963093)
      ["request"]=> array(0) {}
    }
  }
[#<AuthRocket::Session:0x3fc21972f554>
  id: "kss_0vAAjvavvCaZQd76VvFt4b",
  attribs: {
    "user_id"=>"usr_0v9hKVEVrWq5y7whHzSVgh",
    "object"=>"session",
    "created_at"=>1423941493.701,
    "expires_at"=>1423963093,
    "request" : {
      "ip"=>"10.0.0.1",
      "client"=>"MyApp for iOS/v1.0.0"
    }
  },
  metadata: {
    "more_results"=>false
  }
]

Get a session

Retrieve an active session by the session ID.

Associated user’s state must be active.

Parameters

ParamValueDefault
expand memberships

See below.
org_id org_id

Include only this org_id in JWT and memberships (if expanded).

expand

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/:session_id

var resp = await authrocket.sessions.find('kss_SAMPLE')
$res = $authrocket->sessions->find('kss_SAMPLE');
session = AuthRocket::Session.find 'kss_SAMPLE'

Response

Example

Status: 200

{ "id" : "kss_0vAAjvavvCaZQd76VvFt4b",
  "user_id" : "usr_0v9hKVEVrWq5y7whHzSVgh",
  "object" : "session",
  "created_at" : 1423941493.701,
  "expires_at" : 1423963093,
  "request" : {
    "ip" : "10.0.0.1",
    "client" : "Firefox/35.0"
  },
  "user" : { ... }
}

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

console.log(resp.results)
{ id: "kss_0vAAjvavvCaZQd76VvFt4b",
  user_id: "usr_0v9hKVEVrWq5y7whHzSVgh",
  object: "session",
  created_at: 1423941493.701,
  expires_at: 1423963093,
  request: { ... },
  user: { ... }
}
var_dump($res->fields);
  array(7) {
    ["id"]=> string(26) "kss_0vAAjvavvCaZQd76VvFt4b"
    ["user_id"]=> string(26) "usr_0v9hKVEVrWq5y7whHzSVgh"
    ["object"]=> string(7) "session"
    ["created_at"]=> float(1423941493.701)
    ["expires_at"]=> int(1423963093)
    ["request"]=> array(0) {}
    ["user"]=> array(18) { ... }
  }
#<AuthRocket::Session:0x3fc21972f554>
  id: "kss_0vAAjvavvCaZQd76VvFt4b",
  attribs: {
    "user_id"=>"usr_0v9hKVEVrWq5y7whHzSVgh",
    "object"=>"session",
    "created_at"=>1423941493.701,
    "expires_at"=>1423963093,
    "request" : {
      "ip"=>"10.0.0.1",
      "client"=>"Firefox/35.0"
    },
    "user" : #<AuthRocket::User:0x3fde5fa18df8> ...
  }

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)
{ id: 'kss_0vom4PX0VnBMO66utSJpyB',
  object: 'session',
  created_at: 1580238594,
  expires_at: 1580260194,
  token: 'original-token',
  user_id: 'usr_0vom4PWTx2p2PX92C4Swad',
  user: {
    id: 'usr_0vom4PWTx2p2PX92C4Swad',
    object: 'user',
    realm_id: 'rl_0vom4PW0nmIBY76D4sGgI3',
    username: 'dave',
    first_name: null,
    last_name: null,
    name: 'dave',
    email: 'dave@example.com',
    email_verification: 'none',
    reference: undefined,
    custom: undefined,
    memberships: [{
      id: 'mb_0vom4PWqxSfcmC2N5TSxNP',
      object: 'membership',
      permissions: ['forum:admin'],
      user_id: 'usr_0vom4PWTx2p2PX92C4Swad',
      org_id: 'org_0vom4PWlIrKTIci1I2sNr5',
      org: {
        id: 'org_0vom4PWlIrKTIci1I2sNr5',
        object: 'org',
        realm_id: 'rl_0vom4PW0nmIBY76D4sGgI3',
        name: 'Widgets Inc',
        reference: undefined,
        custom: undefined
      }
    }]
  }
}

Note: returned objects contain only the attributes available inside the JWT token and will not be complete.

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) {
    ["id"]=> string(26) "kss_0vAAjvavvCaZQd76VvFt4b"
    ["object"]=> string(7) "session"
    ["created_at"]=> int(1423941493)
    ["expires_at"]=> int(1423963093)
    ["token"]=> string(100) "original-token"
    ["user_id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
    ["user"]=> array(12) {
      ["id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
      ["username"]=> string(4) "dave"
      ["first_name"]=> NULL
      ["last_name"]=> NULL
      ["name"]=> string(4) "dave"
      ["email"]=> string(16) "dave@example.com"
      ["email_verification"]=> string(4) "none"
      ["reference"]=> NULL
      ["custom"]=> NULL
      ["memberships"]=> array(1) {
        [0]=>
        array(6) {
          ["id"]=> string(25) "mb_0v1zWp1IEkl40q69WIQRaN"
          ["object"]=> string(10) "membership"
          ["permissions"]=> array(1) {
            [0]=> string(11) "forum:admin"
          }
          ["user_id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
          ["org_id"]=> string(26) "org_0v1zWRHJVm7JY8vUqDRuyx"
          ["org"]=> array(6) {
            ["id"]=> string(26) "org_0v1zWRHJVm7JY8vUqDRuyx"
            ["object"]=> string(3) "org"
            ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
            ["name"]=> string(11) "Widgets Inc"
            ["reference"]=> NULL
            ["custom"]=> NULL
          }
        }
      }
    }
  }

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:0x3fc21972f554>
  id: "kss_0vAAjvavvCaZQd76VvFt4b",
  attribs: {
    "object"=>"session",
    "created_at"=>1423941493,
    "expires_at"=>1423963093,
    "token"=>"original-token",
    "user_id"=>"usr_0v9hKVEVrWq5y7whHzSVgh",
    "user"=>#<AuthRocket::User:0x3fc21aaf3acc>
      id: "usr_0v9hKVEVrWq5y7whHzSVgh",
      attribs: {
        "object"=>"user",
        "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
        "username"=>"dave",
        "first_name"=>nil,
        "last_name"=>nil,
        "name"=>"dave",
        "email"=>"dave@example.com",
        "email_verification"=>"none",
        "reference"=>nil,
        "custom"=>nil,
        "memberships"=>[
          #<AuthRocket::Membership:0x3fc21ab07f40>
            id: "mb_0v1zWp1IEkl40q69WIQRaN",
            attribs: {
              "object"=>"membership",
              "permissions"=>["forum:admin"],
              "org_id"=>"org_0v1zWRHJVm7JY8vUqDRuyx",
              "user_id"=>"usr_0v9hKVEVrWq5y7whHzSVgh",
              "org"=>#<AuthRocket::Org:0x3fc21aaf2a00>
                id: "org_0v1zWRHJVm7JY8vUqDRuyx",
                attribs: {
                  "object"=>"org",
                  "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
                  "name"=>"Widgets Inc",
                  "reference"=>nil,
                  "custom"=>nil
                }
        ]
      }
  }

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

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

var resp = await authrocket.sessions.create({
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  request: {ip: "10.0.0.1", client: "MyApp for iOS/v1.0.0"}
})
$res = $authrocket->sessions->create([
  "user_id" => "usr_0v1zUpWdE4IiFc2w5ynShf",
  "request" => ["ip" => "10.0.0.1", "client" => "MyApp for iOS/v1.0.0"]
]);
session = AuthRocket::Session.create(
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  request: {ip: "10.0.0.1", client: "MyApp for iOS/v1.0.0"}
)

Response

Example

Status: 201 with same body as Get a Session.:

Status: 404 if user not found or not active.

On success, returns same object as Get a Session.

On failure, throws an exception.

On success, returns same object as Get a Session.

On failure, throws an exception.

On success, returns same object as Get a Session.

On failure, raises 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/:session_id

var resp = await authrocket.sessions.delete('kss_SAMPLE')
$res = $authrocket->sessions->delete('kss_SAMPLE');
AuthRocket::Session.delete 'kss_SAMPLE'

Response

Example

Status: 204

On success, returns an object with no errors.

On failure, returns an object with errors.

resp.hasErrors()
// => true

On success, returns an object with no errors.

On failure, returns an object with errors.

$res->hasErrors();
// => true

On success, returns partial object.

On failure, returns false.

Events

Does not trigger any events.

Contents
Fields Required permissions List sessions for a user Get a session Decode a session token Create a session Delete a session