Sessions

Every request your client makes to Nakama must be authorized. A session is the period of authenticated access that makes this possible: when a player authenticates, Nakama issues a signed JSON Web Token (JWT) that your client presents with each subsequent request. Because the token is cryptographically signed, Nakama validates it in memory without a database lookup on every call.

Sessions are time-limited by design. Nakama issues two tokens at authentication: a short-lived session token for authorizing requests, and a longer-lived refresh token for obtaining a new session token without requiring the player to sign in again.

Set both values in your server configuration. The session token lifetime controls how often your client refreshes. The 60-second default is intentionally short, and most production deployments set it to around 2 to 3 times the game’s average play session.

The refresh token lifetime determines how long a player stays logged in between sessions without re-authenticating. A typical range is 24 hours to 30 days.

Session details #

Access a user’s ID, name, and whether or not their session has expired:

1
2
3
4

const id = "3e70fd52-7192-11e7-9766-cb3ce5609916";
const session = await client.authenticateDevice(id)
console.info("id:", session.user_id, "username:", session.username);
console.info("Session expired?", session.isexpired(Date.now() / 1000));

1
2
3
4

const string id = "3e70fd52-7192-11e7-9766-cb3ce5609916";
var session = await client.AuthenticateDeviceAsync(id);
System.Console.WriteLine("Id '{0}' Username '{1}'", session.UserId, session.Username);
System.Console.WriteLine("Session expired? {0}", session.IsExpired);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

auto loginFailedCallback = [](const NError& error)
{
};

auto loginSucceededCallback = [](NSessionPtr session)
{
    cout << "id " << session->getUserId() << " username " << session->getUsername() << endl;
    cout << "Session expired? " << (session->isExpired() ? "yes" : "no") << endl;
};

std::string deviceId = "3e70fd52-7192-11e7-9766-cb3ce5609916";

client->authenticateDevice(deviceId, opt::nullopt, opt::nullopt, {}, loginSucceededCallback, loginFailedCallback);

1
2
3

var deviceid = SystemInfo.deviceUniqueIdentifier;
Session session = client.authenticateDevice(deviceid).get();
System.out.format("Session %s", session.getAuthToken());

1
2
3
4
5
6
7
8

var session : NakamaSession = yield(client.authenticate_device_async(deviceid), "completed")

if session.is_exception():
    print("An error occurred: %s" % session)
    return

print("Id '%s' Username '%s'" % [session.id, session.username])
print("Session expired? %s" % session.expired)

1
2
3
4
5
6
7
8

var session : NakamaSession = await client.authenticate_device_async(deviceid)

if session.is_exception():
    print("An error occurred: %s" % session)
    return

print("Id '%s' Username '%s'" % [session.id, session.username])
print("Session expired? %s" % session.expired)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

local result = client.authenticate_device(defold.uuid())

if result.error then
  print(result.message)
  return
end

print(("Id '%s' Username '%s' "):format(result.user_id, result.username))

if os.time() > result.expires then
  print("Session has expired")
end

1
2
3
4

let id = "3e70fd52-7192-11e7-9766-cb3ce5609916"
var session = await client.authenticateDevice(id: id)
debugPrint("Id: \(session.userId)", "Username: \(session.username)")
debugPrint("Session expired? \(session.isExpired)")

1
2
3
4

final id = '3e70fd52-7192-11e7-9766-cb3ce5609916';
final session = await client.authenticateDevice(deviceId: id);
print('Id: ${session.userId}, Username: ${session.username}');
print('Session expired? ${session.isExpired}');

Session refresh #

When the session token expires, call the session refresh endpoint with the refresh token to receive a new session token and refresh token pair. If the refresh token has also expired, or the session has been revoked via logout, the player must re-authenticate.

1

client->authenticateRefresh(session);

1

client.session_refresh(session.refresh_token)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

POST /v2/session/refresh/
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Basic base64(ServerKey:)
{
  "token": "<Refresh token>",
  "vars": {
    "key": "value",
    "key2": "value2"
  }
}

1

session = yield(client.session_refresh_async(session), "completed)

1

session = await client.session_refresh_async(session)

1

session = await client.sessionRefresh(session);

1

session = await client.SessionRefreshAsync(session);

1

session = await client.refreshSession(session: session)

1

session = await client.sessionRefresh(session: session);

You can optionally provide new session variable values when refreshing a session. These new values will replace any session variables currently stored in the session object.

How auto-refresh works #

Most Nakama client SDKs refresh sessions automatically. Before each API call, the client checks whether the session token expires within the next five minutes and calls the refresh endpoint transparently. To confirm whether your SDK supports this, check its client library documentation for an autoRefreshSession parameter on the Client constructor. If present, auto-refresh is enabled by default.

The following shows the pattern for .NET and Unity:

1
2
3
4
5
6

// Auto-refresh is enabled by default.
var client = new Client("http", "127.0.0.1", 7350, "defaultkey");

// To opt out, pass false as the last argument.
var client = new Client("http", "127.0.0.1", 7350, "defaultkey",
    UnityWebRequestAdapter.Instance, autoRefreshSession: false);

When a session refreshes, the SDK fires a ReceivedSessionUpdated event with the updated session. Subscribe to this event and save the tokens to persistent storage. You’ll need the refresh token on the next app start.

1
2
3
4

client.ReceivedSessionUpdated += updatedSession => {
    PlayerPrefs.SetString("nakama.authToken", updatedSession.AuthToken);
    PlayerPrefs.SetString("nakama.refreshToken", updatedSession.RefreshToken);
};

On app start, restore the session from storage. If the auth token has expired, use the refresh token to get a new one silently rather than forcing the player to log in again. Only fall back to full authentication if the refresh token has also expired.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

var authToken = PlayerPrefs.GetString("nakama.authToken");
var refreshToken = PlayerPrefs.GetString("nakama.refreshToken");

if (!string.IsNullOrEmpty(refreshToken))
{
    var session = Session.Restore(authToken, refreshToken);
    if (session.IsExpired)
    {
        session = await client.SessionRefreshAsync(session);
        PlayerPrefs.SetString("nakama.authToken", session.AuthToken);
        PlayerPrefs.SetString("nakama.refreshToken", session.RefreshToken);
    }
}
else
{
    // No stored session — authenticate from scratch.
}

If your SDK doesn’t support auto-refresh, call the session refresh endpoint manually before the session token expires.

Session logout #

It is good security practice to enable users to logout of an active session. This can be used to prevent unauthorized access by another person when using a shared device, for example.

1

client.session_logout(session.refresh_token, session.token)

1
2
3
4
5
6
7
8
9

POST /v2/session/logout/
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Basic base64(ServerKey:)
{
  "token": "<Session token to log out>",
  "refreshToken": "<Refresh token to invalidate>"
}

1

yield(client.session_logout_async(session), "completed")

1

await client.session_logout_async(session)

1

await client.sessionLogout(session);

1

await client.SessionLogoutAsync(session);

1

await client.sessionLogout(session: session)

1

await client.sessionLogout(session: session);

Logging out of a user’s session invalidates their authentication and refresh tokens, but does not disconnect their open socket connections. This can be accomplished via the server-side sessionDisconnect function. See the corresponding function reference.

Session variables #

Session variables allow clients and server-side code to embed additional key/value pairs into the session token generated by the game backend. This enables the session token to act as an edge cache, with the information available as long as the session remains active.

These can be used to implement different features and tools, such as analytics, referral bonuses, or rewards programs.

You can optionally provide new session variable values when refreshing a session. These new values will replace any session variables currently stored in the session object.

Setting with client #

To set the variables in the client’s request for authentication use:

1
2
3

local vars = { key = "value" }
local create = true
local result = client.authenticate_email(email, password, vars, create, "mycustomusername")

1
2
3
4
5

Map<String, String> vars = new HashMap<>();
vars.put("Key", "Value");
vars.put("Key2", "Value2");

Session session = client.authenticateEmail("<email>", "<password>", vars).get();

1
2
3
4
5
6
7

var vars = {
    "key" : "value",
    "key2" : "value2"
    # ...
}

var session : NakamaSession = yield(client.authenticate_email_async("<email>", "<password>", null, true, vars), "completed")

1
2
3
4
5
6
7

var vars = {
    "key" : "value",
    "key2" : "value2"
    # ...
}

var session : NakamaSession = await client.authenticate_email_async("<email>", "<password>", null, true, vars)

1
2
3
4
5

var vars = new Dictionary<string, string>();
vars["key"] = "value";
vars["key2"] = "value2";
// ...
var session = await client.AuthenticateEmailAsync("<email>", "<password>", null, true, vars);

1
2
3

const create = true;
const session = await client.authenticateEmail(email, password, create, "mycustomusername", {key: "value"});
console.info("Successfully authenticated:", session);

1
2
3

curl "http://127.0.0.1:7350/v2/account/authenticate/email?create=true&username=mycustomusername" \
--user 'defaultkey:' \
--data '{"email": "hello@heroiclabs.com", "password": "password", "vars": { "key": "value" }}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

POST /v2/account/authenticate/email?create=true&username=mycustomusername
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
    "email": "hello@heroiclabs.com",
    "password": "password",
    "vars": {
        "key": "value"
    }
}

1
2
3
4
5
6

let vars: [String : String] = [
    "key": "value",
    "key2": "value2"
]
// ...
let session = await client.authenticateEmail(email: "<email>", password: "<password>", create: false, username: nil, vars: vars)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

final Map<String, String> vars = {
  'key': 'value',
  'key2': 'value2',
};
// ...
final session = await client.authenticateEmail(
  email: '<email>',
  password: '<password>',
  create: false,
  username: null,
  vars: vars,
);

This example shows setting session variables with Email Authentication, but this feature is available for all of the other authentication options and in all client libraries.

Setting with server #

Session variables may be set by the server, but only in the before authentication hooks.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

local nk = require("nakama")

local function set_session_vars(context, payload)
  nk.logger_info("User session contains key-value pairs set by the client: " .. nk.json_encode(payload.account.vars))

  payload.account.vars["key_added_in_lua"] = "value_added_in_lua"
  return payload
end

nk.register_req_before(set_session_vars, "AuthenticateEmail")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
    if err := initializer.RegisterBeforeAuthenticateEmail(SetSessionVars); err != nil {
        logger.Error("Unable to register: %v", err)
        return err
    }

    return nil
}

func SetSessionVars(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateEmailRequest) (*api.AuthenticateEmailRequest, error) {
    logger.Info("User session contains key-value pairs set the client: %v", in.GetAccount().Vars)

    if in.GetAccount().Vars == nil {
        in.GetAccount().Vars = map[string]string{}
    }

    in.GetAccount().Vars["key_added_in_go"] = "value_added_in_go"

    return in, nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

let setSessionVars: nkruntime.BeforeHookFunction<nkruntime.AuthenticateEmailRequest> = function (context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, payload: nkruntime.AuthenticateEmailRequest) {
  payload.account.vars = {
    key: 'key',
    value: 'value',
  }

  return payload;
}

function InitModule(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  initializer.registerBeforeAuthenticateEmail(setSessionVars);
}

Accessing with server #

Once set, session variables become read-only and may be accessed in any server hook. The only way to change or delete a session variable is through forcing the client to authenticate again.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

let accessSessionVars: nkruntime.BeforeHookFunction<nkruntime.GetAccountRequest> = function (
  context: nkruntime.Context,
  logger: nkruntime.Logger,
  nk: nkruntime.Nakama,
  payload: nkruntime.GetAccountRequest
) {
  if (context.vars) {
    logger.info("User session contains key-value pairs set by both the client and the before authentication hook: %q", context.vars);
  } else {
    logger.info("No session variables were found.");
  }

  return payload;
}

let InitModule: nkruntime.InitModule = function (
  ctx: nkruntime.Context,
  logger: nkruntime.Logger,
  nk: nkruntime.Nakama,
  initializer: nkruntime.Initializer
) {
  initializer.registerBeforeGetAccount(accessSessionVars);
}

1
2
3
4
5
6
7
8
9

local nk = require("nakama")

local function access_session_vars(context, payload)
  nk.logger_info("User session contains key-value pairs set by both the client and the before authentication hook: " .. nk.json_encode(context.vars))

  return payload
end

nk.register_req_before(access_session_vars, "GetAccount")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
    if err := initializer.RegisterBeforeGetAccount(AccessSessionVars); err != nil {
        logger.Error("Unable to register: %v", err)
        return err
    }

    return nil
}

func AccessSessionVars(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule) error {
    vars, ok := ctx.Value(runtime.RUNTIME_CTX_VARS).(map[string]string)

    if !ok {
        logger.Info("User session does not contain any key-value pairs set")
        return nil
    }

    logger.Info("User session contains key-value pairs set by both the client and the before authentication hook: %v", vars)
    return nil
}

Related Pages

• Session Management