JWT specification

This document describes how JWTs (JSON web token) need to be structured in order to be used in post-purchase app extensions on the Shopify checkout. It describes the claims that can be used, and whether they're optional.

Overview

The data passed from Shopify to the extension point is signed with a shared secret (JWT). When you make a call to your backend server, you can use this secret to verify that the request came from Shopify. The following example displays how you can use a changeset token to request changes to an initial purchase:

If your app makes a return call to your extension point, then you must sign applyChangeset with the shared secret. Shopify will use the secret to verify that the request is coming from your app.

Encoding and decoding

JWTs can be encoded and decoded by using the API secret key of an app as the token key, and by setting the hashing algorithm to HS256.

Ruby example:

Claims

JWT ID (JTI)

Used to make sure each token is unique, and prevent potential replay attacks.

  • Shopify issued token: Not present.
  • Partner issued token: Required. It is strongly recommend to use UUIDs, to ensure each token is unique.

Issuer (ISS)

Used to identify who issued the token.

  • Shopify issued token: Always present, and statically set to "shopify".
  • Partner issued token: Required. The api_key of the app issuing the token.

Subject (SUB)

The reference ID of the initial purchase the token was issued for.

  • Shopify issued token: Always present.
  • Partner issued token: Required.

Issued at time (IAT)

Used to identify when the token was generated.

  • Shopify issued token: Always present.
  • Partner issued token: Required.

Expiration time (EXP)

Used to prevent a token from being used after a certain time.

  • Shopify issued token: Not present.
  • Partner issued token: Optional.

Not before time (NBF)

Used to prevent a token from being used before a certain time.

  • Shopify issued token: Not present.
  • Partner issued token: Optional.

Audience (AUD)

Unused.