• Overview
  • Encoding and decoding
  • Claims

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

Anchor link to section titled "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

Anchor link to section titled "Encoding and decoding"

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

Ruby example:

Claims

Anchor link to section titled "Claims"

JWT ID (JTI)

Anchor link to section titled "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)

Anchor link to section titled "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)

Anchor link to section titled "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)

Anchor link to section titled "Issued at time (IAT)"

Used to identify when the token was generated.

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

Note

As a security measure, changesets signed before the initial purchase is completed aren't accepted.

Expiration time (EXP)

Anchor link to section titled "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)

Anchor link to section titled "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)

Anchor link to section titled "Audience (AUD)"

Unused.

On this page

  • Overview
  • Encoding and decoding
  • Claims