AuthRocket
These docs are for AuthRocket 1. Looking for AuthRocket 2 docs?

Sessions

The sessions resource provides access to create and manage sessions.

Creating sessions works whether the Realm is in unmanaged or managed session mode.

Unmanaged sessions aren’t stored or tracked by AuthRocket and therefore aren’t accessible via other session APIs. (But, see Decode a Token.)

Only human users can have managed sessions. When api keys are used for authentication, the returned tokens are always unmanaged.

See also Session Concepts and Login Tokens.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Session ID or full login token. 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.

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 /v1/sessions?user_id=usr_0v9hKVEVrWq5y7whHzSVgh

$res = $client->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"
      }
    }
  ]
}

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 or a full login (JWT) token (such as returned by Authenticate a User).

Associated user’s state must be active.

Parameters

ParamValueDefault
expand memberships,
token

See below. Expand multiple as: memberships,token.

expand

  • memberships - Include membership and org details in the response.
  • token - Include JWT with the response. Useful when user/org/membership data has been updated or when only having the session ID.

Request

Example
GET /v1/sessions/:session_id_or_token

$res = $client->sessions()->find('session_id_or_token');
AuthRocket::Session.find 'session_id_or_token'

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.

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

Our Ruby library also includes a method to decode an existing JWT token without making an API call. This verifies expiration time data within the token (if present), but doesn’t not check to see if the session has been subsequently deleted.

Unlike the other methods in the Session resource, this particular method is also valid for all unmanaged session tokens, such as those generated for api_key authentication.

Request

Example
$res = $client->sessions()->fromToken('session_token');
session=AuthRocket::Session.from_token 'session_token'

Response

Example

On success, returns response similar to Get a Session, with nested User and possibly Membership+Org arrays.

Note that all returned arrays contain only the data available from the JWT token, and will not be complete. If you need the additional attributes, use Get a Session with either the token or the id.

If token is invalid or expired, returns null.

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

#<AuthRocket::Session:0x3fc21972f554>
  id: "kss_0vAAjvavvCaZQd76VvFt4b",
  attribs: {
    "object"=>"session",
    "created_at"=>1423941493.701,
    "expires_at"=>1423963093,
    "user_id"=>"usr_0v9hKVEVrWq5y7whHzSVgh",
    "user"=>#<AuthRocket::User:0x3fc21aaf3acc>
      id: "usr_0v9hKVEVrWq5y7whHzSVgh",
      attribs: {
        "username"=>"dave",
        "name"=>"dave",
        "first_name"=>nil,
        "last_name"=>nil,
        "memberships"=>[
          #<AuthRocket::Membership:0x3fc21ab07f40>
            attribs: {
              "permissions"=>["forum:admin"],
              "org"=>#<AuthRocket::Org:0x3fc21aaf2a00>
                id: "org_0v1zWRHJVm7JY8vUqDRuyx",
                attribs: {
                  "name"=>"Widgets Inc",
                },
              "org_id"=>"org_0v1zWRHJVm7JY8vUqDRuyx",
              "user_id"=>"usr_0v9hKVEVrWq5y7whHzSVgh",
          ...
        ]
      },
  }

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

user = session.user
user.email # => nil
user.reload
user.email # => john.doe@example.com
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 or Authenticate Using an API key.

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 /v1/sessions

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

$res = $client->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, plus:

{ ... ,
  "token" : "4JagCZeSCVH...ae2kd9ZOaWo"
}

Status: 404 if user not found, not active, or not a human.

On success, returns same object as Get a Session plus a token attribute.

On failure, throws an exception.

On success, returns same object as Get a Session plus a token attribute.

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 /v1/sessions/:session_id_or_token

$res = $client->sessions()->delete('session_id_or_token');
AuthRocket::Session.delete 'session_id_or_token'

Response

Example

Status: 204

On success, returns an object with no errors.

On failure, returns an object with errors.

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

On success, returns partial object.

On failure, returns false.

Events

Does not trigger any events.

Questions? Find a Typo? Get in touch.

Back to All Docs