Shopify Multipass: Complete SSO Developer Implementation Guide (2026)

If you run a Shopify Plus store alongside an external website, membership platform, or SaaS application, you have likely encountered a frustrating user experience problem: customers must log in separately on each platform. Shopify Multipass solves this by allowing your external system to authenticate a user and seamlessly transfer that authenticated session into Shopify — no second login required. This guide covers everything a developer needs to know about Shopify Multipass, from cryptographic fundamentals to production-ready code and security hardening.

What Is Shopify Multipass and How Does It Work?

Shopify Multipass is a Single Sign-On (SSO) mechanism exclusive to Shopify Plus merchants. Per the official Shopify Multipass API documentation, it allows a trusted external application to generate a cryptographically signed token that, when redeemed at a special Shopify endpoint, automatically logs the customer into the Shopify storefront — creating the account if it does not already exist.

The mechanism relies on symmetric cryptography. Your server — and only your server — holds a secret key issued by Shopify. Using that secret you encrypt a JSON payload describing the customer, then sign the ciphertext with HMAC-SHA256. Shopify verifies the signature, decrypts the payload, and establishes the customer session. Because the secret never leaves your server, only your application can produce a valid token.

Key characteristics of Shopify Multipass:

• Available exclusively on Shopify Plus plans.
• Tokens are single-use — each redirect generates a fresh token.
• Tokens carry a timestamp (created_at) and Shopify rejects tokens older than 90 seconds.
• If the customer email does not exist in Shopify, an account is created automatically.
• No OAuth dance, no redirect to Shopify login — the redirect itself completes authentication.

Shopify Multipass Use Cases

Because Shopify Multipass delegates identity entirely to your system, it fits any architecture where an external authority owns the user database:

External User Management Systems

Organizations that manage customers in a CRM, ERP, or bespoke identity provider can bridge those accounts into Shopify without duplicating credentials. The external system remains the source of truth; Shopify consumes the identity on demand.

SaaS Platforms with an Embedded Store

A SaaS product that sells add-ons, credits, or physical merchandise through a Shopify storefront can drop users directly into the cart or checkout page already authenticated, dramatically reducing drop-off.

Membership and Subscription Sites

Platforms built on WordPress, Drupal, or a custom stack often gate content behind a login. Adding a Shopify store to the same ecosystem without forcing a second login is a textbook Shopify Multipass SSO scenario.

Multi-Storefront Architectures

Merchants operating several Shopify Plus stores under a single brand can build a central identity layer and issue Shopify Multipass tokens to each store, giving customers a unified login experience across all storefronts.

How Shopify Multipass SSO Works Under the Hood

The Shopify Multipass SSO token lifecycle consists of six distinct stages:

1. Customer authenticates on your platform (username/password, OAuth, magic link, etc.).
2. Your server builds a JSON payload with the customer's email, name, and a precise created_at ISO 8601 timestamp.
3. Your server derives two 16-byte keys from the Multipass secret using SHA-256: the first half becomes the AES encryption key, the second half becomes the HMAC signing key.
4. Your server encrypts the JSON using AES-128-CBC with a random 16-byte IV prepended to the ciphertext.
5. Your server signs the IV+ciphertext blob with HMAC-SHA256 and appends the 32-byte signature.
6. Your server base64url-encodes the combined binary (IV + ciphertext + HMAC) and appends it to the Multipass URL, then redirects the customer's browser.

On receipt, Shopify performs the same derivation using the shared secret, verifies the HMAC, rejects expired tokens, decrypts the payload, and upserts the customer record before issuing a session cookie. The entire exchange happens over a single HTTPS redirect — transparent to the end user.

Implementing Shopify Multipass: Step-by-Step

1. Enable Multipass in Shopify Admin

Navigate to Shopify Admin → Settings → Customer accounts. Under the Multipass section, toggle Enable Multipass login. This action generates your Multipass secret and reveals the token endpoint URL in the format:

https://.myshopify.com/account/login/multipass/

2. Generate and Store Your Multipass Secret

Shopify displays the secret once after enabling the feature. Copy it immediately and store it in a secrets manager (AWS Secrets Manager, HashiCorp Vault, environment variable injected at runtime — never hard-coded in source). If you lose the secret, you must generate a new one, which invalidates all previously issued tokens.

3. Derive Encryption and Signature Keys

Compute a SHA-256 hash of the UTF-8-encoded secret. Split the 32-byte digest: bytes 0–15 become the encryption key; bytes 16–31 become the signature key.

4. Build the Token Payload (JSON Structure)

The minimum required field is email. The created_at field must be an ISO 8601 string with timezone offset. Optional fields let you pre-populate the customer record:

{
  "email": "customer@example.com",
  "created_at": "2026-04-20T14:30:00-00:00",
  "first_name": "Jane",
  "last_name": "Doe",
  "tag_string": "vip,wholesale",
  "identifier": "external-user-id-abc123",
  "remote_ip": "203.0.113.42",
  "return_to": "https://store.example.com/collections/all"
}

The return_to field redirects the customer to a specific page after login. The identifier field stores an external ID for cross-system reconciliation.

5. Encrypt with AES-128-CBC

Generate a cryptographically random 16-byte IV for every token. Encrypt the JSON string with AES-128-CBC using the derived encryption key. Prepend the IV to the ciphertext:

binary_token = IV (16 bytes) + AES_CBC_encrypt(json, encryption_key, IV)

6. Sign with HMAC-SHA256

Compute an HMAC-SHA256 over the IV+ciphertext binary using the derived signature key. Append the 32-byte HMAC to the binary token:

signed_token = IV + ciphertext + HMAC_SHA256(IV + ciphertext, signature_key)

7. Base64 Encode and Redirect

Base64url-encode the signed binary (standard base64 with + → - and / → _, no padding or with = stripped depending on implementation). Construct the redirect URL and send the customer's browser there via an HTTP 302 response.

Shopify Multipass Code Examples

Node.js Implementation

The following is a complete, production-ready Shopify Multipass Node.js implementation using only the built-in crypto module. This is one of the most common Shopify Multipass implementation approaches for modern JavaScript backends.

const crypto = require('crypto');

class ShopifyMultipass {
  constructor(secret) {
    // Derive 32-byte key material from the Multipass secret
    const keyMaterial = crypto
      .createHash('sha256')
      .update(secret, 'utf8')
      .digest();

    this.encryptionKey = keyMaterial.subarray(0, 16);
    this.signatureKey  = keyMaterial.subarray(16, 32);
  }

  generateToken(customerData) {
    // Ensure created_at is always fresh
    const payload = {
      ...customerData,
      created_at: new Date().toISOString(),
    };

    const json = JSON.stringify(payload);

    // Encrypt
    const iv         = crypto.randomBytes(16);
    const cipher     = crypto.createCipheriv('aes-128-cbc', this.encryptionKey, iv);
    const ciphertext = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()]);

    // Sign
    const ivPlusCiphertext = Buffer.concat([iv, ciphertext]);
    const hmac = crypto
      .createHmac('sha256', this.signatureKey)
      .update(ivPlusCiphertext)
      .digest();

    // Encode
    const token = Buffer.concat([ivPlusCiphertext, hmac])
      .toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_');

    return token;
  }

  generateUrl(customerData, shopDomain) {
    const token = this.generateToken(customerData);
    return `https://${shopDomain}/account/login/multipass/${token}`;
  }
}

// Usage
const multipass = new ShopifyMultipass(process.env.SHOPIFY_MULTIPASS_SECRET);

const url = multipass.generateUrl(
  {
    email:      'customer@example.com',
    first_name: 'Jane',
    last_name:  'Doe',
    return_to:  '/collections/all',
  },
  'your-store.myshopify.com'
);

// In an Express route:
// res.redirect(302, url);
console.log(url);

This Shopify Multipass Node.js snippet handles key derivation, encryption, signing, and URL construction in a reusable class. Always read the secret from an environment variable, never from source code. For more patterns like this, see our guide on building custom Shopify apps.

PHP Implementation

PHP's openssl extension provides all necessary primitives for a complete Shopify Multipass implementation:

encryptionKey = substr($keyMaterial, 0, 16);
        $this->signatureKey  = substr($keyMaterial, 16, 16);
    }

    public function generateToken(array $customerData): string {
        $customerData['created_at'] = (new DateTimeImmutable('now', new DateTimeZone('UTC')))
            ->format(DateTimeInterface::ATOM);

        $json = json_encode($customerData, JSON_THROW_ON_ERROR);
        $iv   = random_bytes(16);

        $ciphertext       = openssl_encrypt($json, 'AES-128-CBC', $this->encryptionKey, OPENSSL_RAW_DATA, $iv);
        $ivPlusCiphertext = $iv . $ciphertext;
        $hmac             = hash_hmac('sha256', $ivPlusCiphertext, $this->signatureKey, true);

        return rtrim(strtr(base64_encode($ivPlusCiphertext . $hmac), '+/', '-_'), '=');
    }

    public function generateUrl(array $customerData, string $shopDomain): string {
        return "https://{$shopDomain}/account/login/multipass/" . $this->generateToken($customerData);
    }
}

// Usage
$multipass = new ShopifyMultipass($_ENV['SHOPIFY_MULTIPASS_SECRET']);
$url = $multipass->generateUrl(
    ['email' => 'customer@example.com', 'first_name' => 'Jane'],
    'your-store.myshopify.com'
);
header("Location: {$url}", true, 302);
exit;

Python Implementation

Python's cryptography library provides AES-CBC and HMAC support suitable for server-side Shopify Multipass token generation:

import hashlib, hmac, json, os, base64
from datetime import datetime, timezone
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.primitives import padding

class ShopifyMultipass:
    def __init__(self, secret: str):
        key_material     = hashlib.sha256(secret.encode('utf-8')).digest()
        self.enc_key     = key_material[:16]
        self.sig_key     = key_material[16:]

    def generate_token(self, customer_data: dict) -> str:
        customer_data = {**customer_data, 'created_at': datetime.now(timezone.utc).isoformat()}
        json_bytes = json.dumps(customer_data).encode('utf-8')

        # Pad to AES block size
        padder     = padding.PKCS7(128).padder()
        padded     = padder.update(json_bytes) + padder.finalize()

        iv         = os.urandom(16)
        cipher     = Cipher(algorithms.AES(self.enc_key), modes.CBC(iv))
        encryptor  = cipher.encryptor()
        ciphertext = encryptor.update(padded) + encryptor.finalize()

        iv_ct = iv + ciphertext
        sig   = hmac.new(self.sig_key, iv_ct, hashlib.sha256).digest()

        token = base64.urlsafe_b64encode(iv_ct + sig).rstrip(b'=').decode('ascii')
        return token

    def generate_url(self, customer_data: dict, shop_domain: str) -> str:
        return f"https://{shop_domain}/account/login/multipass/{self.generate_token(customer_data)}"

# Usage
mp  = ShopifyMultipass(os.environ['SHOPIFY_MULTIPASS_SECRET'])
url = mp.generate_url({'email': 'customer@example.com'}, 'your-store.myshopify.com')
# In Flask/Django: return redirect(url)

Shopify Multipass Security Best Practices

Because Shopify Multipass security depends entirely on the secrecy of your key, a compromised secret allows anyone to authenticate as any customer. Treat this secret with the same rigor as a database root password.

Additional Shopify Multipass security hardening steps:

• Never generate tokens in client-side JavaScript — the secret would be exposed in browser source.
• Implement rate limiting on the token-generation route to prevent enumeration attacks.
• Log token generation events (customer email, server timestamp, IP) for audit purposes — but never log the token itself.
• If your platform supports it, bind the token to the customer's IP via the remote_ip payload field.

Common Shopify Multipass Errors and How to Fix Them

The following errors appear in Shopify's response or the resulting redirect when a Shopify Multipass token is invalid:

"Invalid token" (400 Bad Request)

This is the most common error during Shopify Multipass implementation. Causes include:

• Wrong secret — verify you are reading from the correct environment variable and that it matches the value displayed in Shopify Admin exactly (no trailing whitespace).
• Incorrect key derivation — SHA-256 must be applied to the raw string of the secret, not to a hex-encoded version.
• Encoding mismatch — ensure the base64 output uses URL-safe characters (- and _) and that padding (=) is handled consistently.
• JSON field name typos — email is required; created_at is required and must be a valid ISO 8601 string.

"Token expired" or Silent Redirect to Login Page

Tokens are valid for 90 seconds from created_at. Always generate the token immediately before the redirect — not during page load or cached in a session. Ensure your server clock is synchronized via NTP. A server time drift of even two minutes will cause all tokens to fail.

Redirect Loops

A redirect loop occurs when return_to points to a page that triggers another Shopify Multipass redirect before the session cookie is set. Ensure return_to points to a page that does not re-initiate SSO for already-authenticated sessions. Check your middleware for unconditional SSO redirects that do not inspect the current session state.

Customer Not Found / Duplicate Accounts

Shopify matches customers by email address. If a customer already exists with that email but was created via a different flow (e.g., guest checkout), Shopify links the Multipass session to the existing account. Duplicate accounts typically indicate inconsistent email casing — normalize all emails to lowercase before encoding in the payload.

Shopify Multipass vs Customer Accounts API

With the introduction of Shopify's new Customer Accounts and the Customer Accounts API, developers now have two SSO pathways. Understanding the trade-offs is essential for architectural decisions:

For Shopify Plus merchants who already own the customer identity layer — especially those working with a Shopify Plus agency to build complex commerce architectures — Shopify Multipass remains the faster, simpler path to seamless SSO.

Limitations of Shopify Multipass

Despite its elegance, Shopify Multipass has well-documented limitations that architects must account for:

• No logout propagation. When a customer logs out of your platform, their Shopify session remains active until it expires naturally. You must implement custom logout handling — for example, clearing cookies via a cross-origin iframe call or directing customers to Shopify's /account/logout endpoint explicitly.
• Shopify Plus exclusivity. There is no workaround for this requirement. Non-Plus merchants must use the Customer Accounts API or a third-party SSO app.
• No token revocation. Once a token is generated (and before it expires), there is no API call to invalidate it. The 90-second TTL is the only protection against replay — make token windows as short as operationally feasible.
• Email as the primary key. Shopify links Multipass sessions to existing accounts by email. If a customer changes their email in your external system but not in Shopify, authentication creates a second account.
• No support for passwordless flows natively. Multipass does not replace Shopify's native magic-link or passkey flows for customers who access Shopify directly (e.g., via order confirmation emails).
• Single secret per store. You cannot scope secrets per integration or per environment without maintaining separate Shopify Plus stores.

Conclusion

Shopify Multipass is a powerful, low-complexity tool for delivering seamless single sign-on between an external platform and a Shopify Plus storefront. Its symmetric cryptography model keeps implementation simple — a handful of crypto primitives, a JSON payload, and a redirect — while its short token TTL and HMAC verification provide a solid security baseline. The primary responsibilities fall on you as the implementer: guard the secret, generate tokens server-side only, rotate credentials regularly, and handle logout propagation explicitly since Shopify does not.

For teams building on Shopify Plus, Shopify Multipass is almost always the right SSO choice when you own the identity layer. Where it falls short — logout propagation, non-Plus stores, or complex OAuth integrations — the Customer Accounts API fills the gap. Understanding both tools ensures you architect the right solution for each situation.

If you need expert help designing or implementing a Shopify Multipass SSO solution, our team specializes in Shopify app development and enterprise commerce integrations. Reach out to discuss your architecture.