Using JWTs

A JSON Web Token (JWT) is the authorization mechanism that all of Xively HTTP APIs require to authenticate and authorize any API call. It is an open standard for passing credentials between applications and cloud platforms. The JWT represents a particular user identity that has logged in and opened a session with the API.

When using the Xively platform, JWTs may be specified in different ways depending on where they are used:

Authorization HTTP header

This method is useful for server-side applications and native mobile applications, where there is no user agent capable of managing cookies. With this method, the application must specify the JWT in the Authorization HTTP header as a Bearer token, for example Authorization: Bearer <jwt>.

HTTP Cookie

This method is useful for browser-based applications capable of managing cookies. With this method, the user agent includes the JWT automatically on API calls to the Xively platform.

JWTs are obtained by calling the platform's /auth/login or /oauth2/callback endpoints (/auth/login is used for password-based user authentication, while /oauth2/callback is used for federated login). When calls to these endpoints are successful, an Identity service session begins, and a JWT is returned as both a cookie and as a response header named xively-access-token. The JWT cookie is set as a Secure, HttpOnly cookie for domain=.xively.com.

The JWT contains many properties used by Xivley APIs to identify and authorize the caller, including among others:

  • The Identity profile of the User (called userId)
  • The Account of the User (called accountId)
  • Session ID (called id)

JWT expiry and renewal

There are two factors which govern whether a user's JWT is still valid.

  • Session length. When a user logs in via the Log in endpoint, a session commences which will last until the user calls the Log out endpoint, or the session length expires. By default, the session length is 14 days.

Tip: Session length can be configured by specifying the optional renewalType during the login call. The renewalType can be set to short (30 minutes), remembered (7 days) or extended (100 days).

  • JWT expiry. Every JWT is valid for 20 minutes before it expires and requires a renewal. So long as the user's session has not expired (see above bullet), an expired JWT will still be accepted by Xively, but Xively will renew the old one and return a new JWT in the response as both a cookie and a header that replaces the old expired one. A JWT can be renewed only once.

What if my application makes parallelized calls to Xively?

If your application is using a user's JWT in multiple parallelized calls (for example with Javascript promises), the platform provides a grace period of 60 seconds from the time a JWT is first renewed where it will continue to accept the expired JWT and return the new one. This allows multiple parallel calls to all have their JWTs renewed, so long as they call in within 60 seconds of the first JWT renewal.

One user can have multiple sessions

It is expected that one user might be logged in from multiple places. This results in multiple sessions for the multiple apps. Each session has its own JWT, that is refreshed and the new JWT returned as usual after 20 mins.
Note: Logging out of one session (at POST /sessions/logout) logs out that one session, not all sessions. However, resetting a user’s password invalidates all current sessions.

CSRF Protection

The Xively platform provides features for protection from Cross Site Request Forgery (CSRF) attacks. When a user is logged in using the Identity service, the Identity service will return a CSRF token for the session as both a cookie and a response header named xively-csrf-token. The CSRF cookie is set as a Secure cookie (not HttpOnly) for domain=.xively.com.

When HTTP cookies are used to deliver JWTs, the CSRF token must also be specified. This will happen automatically in user agents.

For applications where the backend performs the Identity service login on behalf of the user (for example, as part of establishing an authenticated web session between the frontend and the backend), the CSRF token can be leveraged for CSRF protection of backend API calls.

The login request returns a Cross Site Request Forgery (CSRF) prevention token and a JSON Web Token (JWT).

Using JWTs