Using JWTs

Authentication of platform API calls is performed using JSON Web Tokens (JWTs), an open standard for passing credentials between applications and cloud platforms.

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.

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, sessions are 14 days in length, but can be configured to be as short as 30 minutes and as long as 100 days by specifying renewalType during the login call.
  • JWT expiry. Every JWT is valid for 20 minutes before it expires and requires 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.

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