Backend Authentication & Authorization - Rebell Developer Center

Trust Model Overview
Actors
Key Rule
Why Mini Apps Cannot Be Trusted
Authorization Code (authCode) Concept
Properties
What authCode Is NOT
What authCode Is Used For
End-to-End Authorization Flow
Sequence Diagram
Flow Steps
Result
Backend Token Exchange & Validation
Exchange Step (Mandatory)
Backend Exchange Implementation
What the Backend Should Store
Session Establishment Patterns
Using the Authenticated Context
Authenticated Request Flow
Backend Implementation
Payments Built on Top of Backend Authorization
Payment Flow Sequence
Security Rules & Anti-Patterns
Hard Rules
Anti-Patterns to Avoid
Backend Endpoint Reference
Bootstrap Endpoint
Backend Must Enforce
Testing Authentication Flow
Test Checklist
Next Steps

Mini Apps run inside the Rebell SuperApp but execute in a client-side sandbox. For security and compliance reasons, the Mini App must be treated as an untrusted client, and every call from the Mini App to the merchant backend must be authenticated and authorized. This section describes the Rebell authorization-code pattern used to establish a trusted user context on the backend. This is the foundation for all other backend operations (orders, user profile access, payments, etc.).

Trust Model Overview

Actors

User

Rebell customer using the SuperApp

Mini App

Runs in Rebell SuperApp (untrusted)

Merchant Backend

Trusted system of record

Rebell OpenAPI

Trusted authorization provider

Key Rule

The Mini App can request authorization and carry an authorization code, but it cannot validate it
The Merchant Backend must exchange the code with Rebell OpenAPI to obtain a trusted user context

Why Mini Apps Cannot Be Trusted

Mini Apps must not be trusted because:

Risk	Description
Environment	They run on end-user devices (modifiable environment)
Replay	Requests can be replayed or forged
Tampering	User identity fields can be tampered with
Secrets	Secrets cannot be safely stored client-side

Therefore:

The backend must never trust userId or similar identifiers coming from the Mini App payload
The backend must use server-side verification via Rebell OpenAPI

Authorization Code (authCode) Concept

An authCode is a short-lived, single-use authorization artifact issued by Rebell after user consent.

Properties

Property	Description
Short-lived	Expires quickly (typically minutes)
Single-use	Cannot be reused after exchange
Bound	Tied to user session, Mini App, and requested scopes

What authCode Is NOT

Not a long-lived token
Not an API key
Not client-verifiable

The authCode expires quickly and cannot be stored for later use

What authCode Is Used For

To let the Merchant Backend exchange it for a trusted user context (and optionally a platform access token / user identifiers, depending on scope).

End-to-End Authorization Flow

Sequence Diagram

Flow Steps

Mini App Requests Authorization

Mini App calls JSAPI to request user authorization with specific scopes

my.getAuthCode({
  scopes: ['auth_user'],
  success: (res) => {
    const authCode = res.authCode;
    bootstrapSession(authCode);
  }
});

User Grants Consent

Platform shows consent prompt; user approves or denies

Mini App Receives authCode

Platform returns short-lived, single-use authCode

Mini App Sends to Backend

Mini App sends authCode to merchant backend bootstrap endpoint

Backend Exchanges authCode

Backend exchanges authCode with Rebell OpenAPI (server-to-server, signed)

Backend Establishes Session

Backend creates internal session and returns session identifier to Mini App

Result

The backend now has a verified user context and can securely act on behalf of that user, within granted scopes.

Backend Token Exchange & Validation

Exchange Step (Mandatory)

When the backend receives authCode, it must:

Validate Format

Validate basic format (non-empty, expected length)

Exchange with Rebell

Exchange it with Rebell OpenAPI (server-to-server, signed request)

Validate Response

Validate the response:

Mini App identifier (if provided)
Granted scopes match what is required
Token/user context is not expired

Create Session

Persist a backend session context

Backend Exchange Implementation

app.post('/session/bootstrap', async (req, res) => {
  const { authCode, miniAppId, deviceId } = req.body;

  // 1. Validate authCode format
  if (!authCode || authCode.length < 10) {
    return res.status(400).json({ error: 'Invalid authCode' });
  }

  try {
    // 2. Exchange authCode with Rebell OpenAPI
    const rebellResponse = await rebellClient.post('/v1/miniapp/auth/token', {
      grantType: 'authorization_code',
      code: authCode
    });

    const { userId, accessToken, scopes, expiresIn } = rebellResponse.data;

    // 3. Validate scopes
    if (!scopes.includes('auth_user')) {
      return res.status(403).json({ error: 'Required scope not granted' });
    }

    // 4. Create backend session
    const session = await createSession({
      rebellUserId: userId,
      scopesGranted: scopes,
      expiresAt: Date.now() + expiresIn * 1000,
      miniAppId,
      deviceId
    });

    // 5. Return session to Mini App
    res.cookie('sessionId', session.id, {
      httpOnly: true,
      secure: true,
      sameSite: 'strict'
    });

    res.json({ success: true });

  } catch (error) {
    console.error('Auth exchange failed:', error);
    res.status(401).json({ error: 'Authorization failed' });
  }
});

What the Backend Should Store

Store a backend session record like:

Field	Description
`sessionId`	Your internal session identifier
`rebellUserId`	Stable user identifier from OpenAPI
`scopesGranted`	List of granted authorization scopes
`issuedAt`	When the session was created
`expiresAt`	When the session expires
`miniAppId`	(Optional) Mini App identifier
`deviceId`	(Optional) Device identifier

Session Establishment Patterns

Choose one approach:

Session Cookie (Recommended)
Session Token

Best for H5 or embedded web UX

Backend returns an HttpOnly secure cookie
Mini App calls backend with cookie automatically
No token management in client code

// Backend sets cookie
res.cookie('sessionId', session.id, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict'
});

Alternative for native Mini Apps

Backend returns sessionId as a bearer token
Mini App sends Authorization: Bearer <sessionId> on each call
Requires token storage in Mini App

// Mini App stores and sends token
my.request({
  url: 'https://api.merchant.com/orders',
  headers: {
    'Authorization': `Bearer ${sessionToken}`
  }
});

Important:

The Mini App must not send authCode again after bootstrap
The backend must treat authCode as single-use

Using the Authenticated Context

Once a session is established, every request from Mini App to backend should rely on the backend session to identify the user — not on client-provided identifiers.

Authenticated Request Flow

Backend Implementation

app.get('/profile', async (req, res) => {
  // Get session from cookie or header
  const sessionId = req.cookies.sessionId ||
                    req.headers.authorization?.replace('Bearer ', '');

  if (!sessionId) {
    return res.status(401).json({ error: 'Not authenticated' });
  }

  // Resolve session to user context
  const session = await getSession(sessionId);

  if (!session || session.expiresAt < Date.now()) {
    return res.status(401).json({ error: 'Session expired' });
  }

  // Use rebellUserId from session - NEVER from request body
  const userProfile = await getUserProfile(session.rebellUserId);

  res.json(userProfile);
});

Key backend rule: Any request requiring user identity must use rebellUserId from session context, never from client-provided values.

Payments Built on Top of Backend Authorization

Payments inside Mini Apps should follow the same trust pattern:

Mini App Triggers

The Mini App triggers a payment action

Backend Creates Payment

The backend creates the payment (using session’s rebellUserId)

Webhook Confirms

The backend receives webhook confirmation

UI Updates

The Mini App UI updates based on backend-confirmed state

Payment Flow Sequence

Security Rules & Anti-Patterns

Hard Rules

Never:

Store secrets or private keys in Mini App code
Call Rebell OpenAPI directly from the Mini App
Trust userId or similar fields from the Mini App request body
Use authCode as a long-lived token
Mark order as paid based on client callback instead of webhook

Always:

Exchange authCode server-side and derive identity from OpenAPI response
Validate webhook signatures for payment confirmation
Use session context for user identity in all backend operations
Enforce session expiry and require re-authorization when needed

Anti-Patterns to Avoid

Anti-Pattern	Risk	Correct Approach
Using `authCode` as long-lived token	Replay attacks	Exchange immediately, use session
Passing `rebellUserId` from client	Identity spoofing	Get from session context only
Creating payments client-side	Unauthorized payments	Create via backend
Trusting client payment callback	False success	Wait for webhook

Backend Endpoint Reference

Bootstrap Endpoint

POST /session/bootstrap

Request:

{
  "authCode": "string (required)",
  "miniAppId": "string (optional)",
  "deviceId": "string (optional)",
  "clientInfo": "object (optional)"
}

Responses:

Status	Description
`200 OK`	Session established, returns cookie/token
`400 Bad Request`	Invalid authCode format
`401 Unauthorized`	authCode exchange failed
`403 Forbidden`	Required scope not granted

Backend Must Enforce

AuthCode One-Time Use

Never accept the same authCode twice. Mark as used after successful exchange.

Scope Checking

Don’t allow user-info access if scope not granted. Validate scopes match requirements.

Session Expiry

If session expired, require re-authorization. Don’t extend sessions indefinitely.

Payment Idempotency

Same paymentRequestId rules as Payment Integration chapter. Prevent duplicate payments.

Testing Authentication Flow

Test Checklist

Happy Path

User grants authorization
authCode exchanged successfully
Session created with correct user context
Subsequent requests use session correctly

Error Cases

Security

Client-provided userId is ignored
authCode cannot be replayed
Session is properly invalidated
Scopes are enforced

Next Steps

With backend authentication implemented, you can now integrate payments:

Payments in Mini Apps

Integrate payment functionality within your Mini App

Payment Integration

Review the complete payment integration guide

Mini App APIs Payments Inside Mini Apps

⌘I

Getting started

Payment Integration

Mini App Development

​Trust Model Overview

​Actors

User

Mini App

Merchant Backend

Rebell OpenAPI

​Key Rule

​Why Mini Apps Cannot Be Trusted

​Authorization Code (authCode) Concept

​Properties

​What authCode Is NOT

​What authCode Is Used For

​End-to-End Authorization Flow

​Sequence Diagram

​Flow Steps

​Result

​Backend Token Exchange & Validation

​Exchange Step (Mandatory)

​Backend Exchange Implementation

​What the Backend Should Store

​Session Establishment Patterns

​Using the Authenticated Context

​Authenticated Request Flow

​Backend Implementation

​Payments Built on Top of Backend Authorization

​Payment Flow Sequence

​Security Rules & Anti-Patterns

​Hard Rules

​Anti-Patterns to Avoid

​Backend Endpoint Reference

​Bootstrap Endpoint

​Backend Must Enforce

​Testing Authentication Flow

​Test Checklist

​Next Steps

Payments in Mini Apps

Payment Integration

Trust Model Overview

Actors

Key Rule

Why Mini Apps Cannot Be Trusted

Authorization Code (authCode) Concept

Properties

What authCode Is NOT

What authCode Is Used For

End-to-End Authorization Flow

Sequence Diagram

Flow Steps

Result

Backend Token Exchange & Validation

Exchange Step (Mandatory)

Backend Exchange Implementation

What the Backend Should Store

Session Establishment Patterns

Using the Authenticated Context

Authenticated Request Flow

Backend Implementation

Payments Built on Top of Backend Authorization

Payment Flow Sequence

Security Rules & Anti-Patterns

Hard Rules

Anti-Patterns to Avoid

Backend Endpoint Reference

Bootstrap Endpoint

Backend Must Enforce

Testing Authentication Flow

Test Checklist

Next Steps