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.
Field | Value | Req/Default | Notes |
---|---|---|---|
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. |
Method | Permissions |
---|---|
List, Get | read |
Create, Delete | write |
List all active sessions belonging to a user.
Param | Value | Default | |
---|---|---|---|
user_id |
id | Filter by user_id | |
sort |
id |
id |
Equivalent to created_at. |
direction |
asc , desc |
asc |
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'
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
}
]
Retrieve an active session by the session ID.
Associated user’s state must be active.
Param | Value | Default | |
---|---|---|---|
expand |
memberships |
See below. |
|
org_id |
org_id | Include only this org_id in JWT and memberships (if expanded). |
memberships
- Include membership and org details in the response, for active orgs only.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.
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'
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> ...
}
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.
var resp = await authrocket.sessions.fromToken('session-token')
$res = $authrocket->sessions->fromToken('session-token');
session = AuthRocket::Session.from_token 'session-token'
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 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.
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"}
)
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.
Does not trigger any events.
Deletes a session.
Will return success if user or session already deleted, so safe to use in all normal circumstances.
DELETE /v2/sessions/:session_id
var resp = await authrocket.sessions.delete('kss_SAMPLE')
$res = $authrocket->sessions->delete('kss_SAMPLE');
AuthRocket::Session.delete 'kss_SAMPLE'
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.
Does not trigger any events.