Protect static files using JSON Web Token (JWT) authentication

On this page

Sirv enables you to create expiring URLs that protect your files from being downloaded or requested with different properties. Sirv's JSON web tokens (JWT) prevent unauthorized viewers from downloading your files or embedding them in other sites.

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. The recipient of the token cannot add, modify or remove any part of the URL, so this is a very effective way of serving dynamic images without allowing the recipient to change the image size, remove a watermark or modify an image in any other way. JWT can be used for protecting any file, not only images.

Generate a JWT Web Token URL

Use Sirv's REST API to generate a JWT token.

1. Ask the Sirv support team to enable JWT tokens for your account.

2. Connect to the REST API.

3. Use the jwt POST method to create a JWT secure file URL.

Example URL

Below is an example of a JWT protected image URL, containing a text overlay "Hello!" encoded in the token and an expiry of 1 year (until May 8, 2021). After that date, the image won't show:

If the claim matches, the image will be returned, otherwise a 403 forbidden error will be returned. Click to open these 3 images and see what is returned:

To check its contents, you can copy the token (shown below) and paste it into a JWT validator. It will show you the header, payload and signature:


Image parameters in a URL

The token can be sent either in the URL or in the request headers.

You can configure a token so that the entire URL must be exact (unchanged) or you can configure it so that some parts of the URL can be modified, such as the width and height. This is useful for using Sirv responsive imaging, allowing different dimension images to be automatically served to different screens/browsers.

Token options

The token can contain many kinds of restrictions, including:

  • Expiration - set a time after which the image will no longer load.
  • Filename mask - specify which filenames the token can be applied to e.g. /path/to/spin1234/* or /path/to/onefile.jpg.
  • Profile - apply a Sirv profile and check that the name of the profile in the URL matches the token.

The filename mask makes it possible to load protected 360 spins, image zooms and other Sirv viewers, while preventing the same token from loading something else (e.g. a different spin or image).

The profile restriction can apply profiles from your Sirv account. This will let you change the appearance of an image in the future, without changing the URL. For example, you could place irremovable text or image watermarks over an image or spin. Any text and watermark option added to the URL will be ignored, preventing a user from deliberately hiding a text or image watermark.

Choose a JWT library

Any JWT library can be used (list of JWT libraries), as long as it adheres to the following requirements:

  • Expiration is required
  • Algorithm is HS256
  • Audience must be a filename prefix, explained below

The audience has a range of possible values:

  • /path/to/file.jpg will match that single file only.
  • /path/to/ will match everything in /path/to folder.
  • /path/t will match /path/to, /path/t1, /path/t2222, etc.
  • / will match every file in the account.

This makes it possible to use JWT for 360 spins (.spin files) as well as any other file in your Sirv account.

Example request

The following JavaScript code sample will request a token (once you've connected to the Sirv REST API):

'use strict';

const { URLSearchParams } = require('url');
const jwt = require('jsonwebtoken');

const filename = '/example-image.jpg';

const params = new URLSearchParams({ // put insecure parameters here
  w: '10%',
  h: '25%'

const data = {
  args: { // put secure parameters here
    text: 'Hello'

const key = 'topsecret';

// generate token
const token = jwt.sign(data, key, {
  algorithm: 'HS256',
  expiresIn: 300, // seconds
  audience: filename

params.append('jwt', token);

console.log('' + filename + '?' + params.toString());

Was this article helpful?

Get help from a Sirv expert