🔒 Requires read-script-tags or write-script-tags access scope.

What are scripts ?

A session token is a short-lived authentication mechanism that lets your app securely validate client-side requests to your backend. It ensures that only authenticated customers can trigger actions or access protected data through your integration.

How it works ?

When your script runs on the customer account, or any supported display scope (via inline JavaScript), it can generate a session token using the getSessionToken() function provided in the injected context.

const sessionToken = getSessionToken(partners_client_key);

Purpose and Usage

The session token is a JWT (JSON Web Token) and acts as a temporary proof of identity for the customer interacting with your app. It has a lifetime of 60 seconds and must be used immediately to authenticate secure AJAX requests from the browser to your backend.

🛠️ Example Use Case

Your app injects inline JavaScript via Recurpay’s script API.
The script calls getSessionToken(partners_client_key) to generate a one-time JWT.

Your frontend includes this token in any outbound request to your backend.

let sessionToken = getSessionToken("client_key_of_partner_app");
$.ajax({
  url: "https://your-app.com/api/something-secure",
  headers: {
    "Authorization": "Bearer " + sessionToken
  },
  ...
});

Once your frontend sends the session token to your backend, your server must validate the token to ensure it's authentic, unexpired, and tied to a valid user and shop.

🔐 Middleware Validation

Your app should have middleware that:
- Detects if a session token is included (usually via the Authorization header).
- Verifies the token's signature using your client secret.
- Parses the token payload and confirms its integrity based on several fields.

🔎 JWT Structure

A session token is a standard JWT (JSON Web Token) in this format: <Header>.<Payload>.<Signature>

✅ Token Verification Checklist

Decoded token details:

Field	Purpose	Validation Rule
exp	Expiration timestamp	Extract the exp value from the payload. Verify that the datetime value is in the future.
nbf	Not-before timestamp	Extract the nbf value from the payload. Verify that the datetime value was in the past.

iss	Issuer (who issued the token)	Must match Recurpay’s domain or token issuer.
dest	Destination domain (Recurpay URL where the token came from)	Must match the Recurpay domain you expect (e.g., store.recurpay.com).
aud	Audience (who the token is intended for)	Must equal your app’s client ID.
sub	Subject (the customer/user ID)	Should be used to identify the customer.

⚠️ If Any Check Fails:

Reject the request immediately.
Return a 401 Unauthorized or appropriate error message.
Do not trust or use the session data.

🛠️ Example: Token Verification Logic:

Pseudocode

const jwt = require('jsonwebtoken');

function verifySessionToken(token) {
  try {
    const payload = jwt.verify(token, CLIENT_SECRET); // Verifies signature
    const now = Math.floor(Date.now() / 1000);

    if (payload.exp < now || payload.nbf > now) throw new Error('Token expired or not yet valid');
    if (!payload.aud || payload.aud !== YOUR_APP_CLIENT_ID) throw new Error('Invalid audience');
    if (!payload.dest.endsWith('.recurpay.com')) throw new Error('Invalid shop domain');

    return payload; // token is valid
  } catch (err) {
    console.error('Invalid session token:', err.message);
    throw new Error('Unauthorized request');
  }
}

If valid, proceed with handling the request as the user is verified.

⚠️ Notes

Tokens are short-lived (60 seconds), you must request a fresh one for each interaction.
You must validate the token server-side using the same secret key used to generate it.
This acts as an additional authentication layer to prevent spoofed or unauthorized requests.