AuthRocket uses tokens to tell your app about new logins. A new, unique token is created everytime someone logs in.
When a user performs a login, a new token is generated and given to the user by LoginRocket. The user then passes that token on to your server so your backend app can verify that token.
AuthRocket’s login tokens are JWT compatible. JWT, which stands for JSON Web Token, is a way of encoding various data into the login token while representing the token as a string of characters. Because they’re simple strings, JWT tokens are extremely easy to pass around between AuthRocket, your user, and your app.
Additionally, JWTs are digitally signed, making it possible to verify that the contents of the JWT are unchanged. Using the signature, your app can verify the token without making an API call back to AuthRocket, reducing login time for your users.
AuthRocket’s JWT tokens also include OpenID Connect compatible fields containing basic information about the user, and optionally, information about their account (memberships and orgs). This wealth of information right in the JWT significantly reduces the number of API calls your app would otherwise have to make, making everything faster.
JWTs are cryptographically signed using either an asymmetric key pair (default) or a shared secret key. AuthRocket uses a unique JWT secret per realm. In our UI, this secret is found on the Integration page of each Realm. It is also available from the Get a Realm API call. The public key half of an asymmetric key pair is also available from LoginRocket at
This secret will be used by your app to verify the JWT and ensure it’s unmodified.
By default we use the RS256 signing algorithm. This key can be made public, making RS256 suitable for verifying keys from within browsers, native apps, or untrusted 3rd-party systems. It is also safe to commit RS256 keys into your code (although you may choose to use ENV variables or other traditional mechanisms instead if switching between realms).
We also support HS256. HS256 keys must be kept secret at all times and keys must be rotated immediately if accidentally disclosed.
AuthRocket provides some official libraries that include JWT verification as well as help decoding the embedded data.
See Decode a Session Token for syntax for each of these.
For other languages, there are a number of available JWT libraries, making JWT support easy to implement.
Some JWT libraries require you to explicitly enable expiration checking (the
exp claim). Others don’t support it at all and will require you to perform such checks yourself. Without expiration checks, login tokens will effectively never expire!
We recommend libraries that automatically check expiration times. All of the above do so.
AuthRocket’s JWT’s contain a variety of user data:
exp- Expiration time
iat- Issued at time
rid- AuthRocket Realm ID
sid- AuthRocket Session ID
sub- AuthRocket User ID
email_verified- One of
family_name- Last name
given_name- First name
locale- User’s preferred locale
name- Full name, ordered by the user’s preferred locale
ref- User’s reference ID
cs- User’s custom attributes
orgs- Array of account (Org + Membership) data:
mid- AuthRocket Membership ID
name- Org name
oid- AuthRocket Org ID
perm- Array of permissions
selected- When multiple orgs, identifies the selected one (
ref- Org’s reference ID
cs- Org’s custom attributes
Null values are simply left out. For example, if a user does not have a first name, the
given_name attribute is left out.
Most token fields are included by default, but a few are optional and must be enabled by setting
orgs(API only; keep reading)
For tokens delivered by LoginRocket,
orgs is always included with exactly one element, matching the current/selected account (org & membership). In multi-user account mode, redirect the user to LoginRocket to switch between accounts. When the user is returned to your app, a new token will be sent with the newly selected account.
For sessions retrieved via the AuthRocket API, both
Realm.jwt_scopes and the query param
org_id affect the results:
For behavior like LoginRocket, include
org_id when using Get a session and exclude
ar.orgs from Realm.jwt_scopes.
Typically JWT tokens are fairly small and are unlikely to cause any operational problems. However, using
cs can add significant amounts of additional data.
This can cause occasional issues with HTTP servers or reverse proxies and may require that such programs be configured to allow long URIs or long headers. Mostly this is only a concern when the token itself is part of the URL.
In our experience, tokens up to 2KB in size will work fine nearly everywhere. Tokens between 2KB and 4KB sometimes require work arounds, but can usually be made to work. Tokens over 4KB may require more attention as to how they are stored and passed around. For example, cookies are limited to 4KB, so a JWT greater than 4KB can’t be stored inside a cookie.
We only use
RS256 (our default) or
HS256 for JWT signing. If your JWT library allows you to specify the expected signing algorithm, we strongly recommend it.