Authenticate an extension built with App Bridge Admin

App Bridge Admin apps use session tokens to authenticate requests between the extension and your backend server. Session tokens are secure packets of data about a merchant session in the Shopify Admin, similar to a cookie. A session token provides the information required to validate that a request is coming from Shopify, and also provides the IDs of the user and shop.

How it works

When your extension built with App Bridge Admin loads in the Shopify Admin, you can use the session token API to fetch the session token. After you have the token, include it with all of the requests you make to your backend server. The token is signed using a shared secret so that your backend can verify if the request is valid.

Make a request to your app’s server using a session token

1. Configure your backend server

Extensions built using App Bridge Admin are hosted on Shopify's servers. To receive requests from your extension, you need to enable cross-domain requests on your backend server.

If you're using Rails, then add the following code in config/application.rb to enable cross-domain requests:

2. Fetch a session token from the Shopify Admin

In your extension, use the session token API to fetch a new session token. Session tokens expire every minute, so always fetch a new token before making a request to your backend server.



3. Make a request to your backend server

After your extension has received a session token, you can include it in requests to your server. How you include the session token in the request is up to you, but we suggest including it in the request header as follows:



Receive a request and decode the session token

When your server receives a request from your extension that includes a session token, you need to decode it. Session tokens use the JSON Web Token (JWT) format. Libraries to encode and decode JWT are available for all common server frameworks.

Pass the following parameters to the JWT decode method:

  • the session token received in your extension's request
  • the api secret key for your app
  • the HS256 algorithm.

Ruby example:

The session token contains information about the current shop and user, including the shop's domain, your app’s API key, and the user ID. You can use this information to establish per-user sessions, similar to an authentication cookie.

Structure of a session token JWT

A decoded Shopify session token contains the following fields:



Sample payload:

Validate a session token

To validate a session token, you can manually validate session tokens, use the shopify app gem, or configure a Rails app to perform the validation.

Manually validate a session token

To verify that a session token is coming from Shopify, you can encode a new session token using your app’s shared secret and compare it to the encoded token received from your extension.

An encoded JSON Web Token (JWT) is a string with the following structure (all three sections are base64 encoded):


The token header and payload are documented in the previous section. The signature verifies that the header and payload were encoded using the shared secret, confirming that the token was generated by Shopify.

To validate a session token manually:

  1. Hash the decoded <header> and <payload> values from the extension session token using the SHA-256 algorithm.

  2. Sign the string using JWT, specifying the HS256 algorithm and using the app’s secret as the signing key.

  3. Base64url-encode the result.

  4. Compare the new session token with the session token received from your extension. If the session tokens are identical, then the request came from Shopify.

Use the shopify app gem to validate a session token

If your server uses the shopify app gem to validate session authentication for GraphQL requests, then requests containing a valid JWT token in the request header will be automatically be authorized. An error is raised if an invalid token is received.

The next steps in this section can be skipped if any of the following criteria are met:

  • The app uses shopify app gem version 13.1.0 or newer.
  • The server doesn’t use Rails.
  • The server is already configured to process GraphQL requests using the shopify app gem.

Configure a Rails app to validate a session token

  1. Add the following route to config/routes.rb:

  2. Replace the contents of app/controllers/graphql_controller.rb with the following code:

Making calls to Shopify’s Admin API

To communicate with the Shopify Admin API, your extension needs to make requests through your backend server. You need to build an API that your extension can call, which in turn calls the Shopify Admin API.

Next steps