# Partner Token Pass-Through

## Overview

Partner Token Pass-Through enables your Micro Web Application (MWA) to call your own partner APIs directly — without requiring members to log in again inside the MWA.

When a member opens your MWA inside the EGYM BMA app, the EGYM platform securely fetches your partner OAuth access token and injects it into the MWA's [initial context](/mwa/docs/native_interface_and_plugins#initial-context) alongside the standard `authToken`. Your MWA can then use this token to authenticate directly against your backend APIs.

Not all BMA have partner token pass-through option, it's obtained during login process for specific kind of integration.
Also, Mobile app should have been released since 20 July 2026 to have a fresh code.

## How It Works

```
Member opens your MWA in EGYM BMA
         │
         ▼
  BMA fetches your partner token from EGYM Galaxy backend
  (token is refreshed automatically if near expiry)
         │
         ▼
  Token is injected into Portals initialContext:
  {
    authToken:     "<EGYM Firebase JWT>",   ← existing, unchanged
    partnerTokens: "{\"<alias>\":\"...\"}"  ← new (JSON-encoded map)
  }
         │
         ▼
  Your MWA reads the token and calls your partner API:
  Authorization: Bearer <partnerTokens["<alias>"]>
```

This flow is **deny-by-default**: tokens are only fetched and injected for MWA features that have been explicitly allowlisted by EGYM via configuration. MWAs that are not configured to receive partner tokens are unaffected.

## Prerequisites

For your MWA to receive a partner token:

1. **Your partner account must be linked** — the member must have previously linked their partner account through the EGYM authentication flow. If the account is not linked, the token will not be present.
2. **The feature must be allowlisted** — EGYM configures your specific MWA feature with your partner alias. No code changes are needed on EGYM's side to add new partners; it is a configuration-only change.


## Reading the Token in Your MWA

The `partnerTokens` field in the initial context is a **JSON-encoded string** containing a map of partner alias → access token.

```typescript
import { getInitialContext } from '@ionic/portals';

interface PortalsContext {
  authToken?: string;
  partnerTokens?: string; // JSON-encoded Record<string, string>
  // ... other fields
}

const context = getInitialContext<PortalsContext>()?.value ?? {};

// Parse the partner tokens map (be defensive: JSON.parse can throw)
let partnerTokens: Record<string, string> = {};
try {
  partnerTokens = JSON.parse(context.partnerTokens ?? '{}') as Record<string, string>;
} catch {
  partnerTokens = {};
}
// Read your token using your partner alias (provided by EGYM)
const myToken = partnerTokens['<your-partner-alias>'];

if (myToken) {
  // Use the token to call your API
  fetch('https://api.yourpartner.com/api/v1/member', {
    headers: { Authorization: `Bearer ${myToken}` },
  });
} else {
  // Handle gracefully: member account not linked or feature not configured
}
```

> **Your partner alias** is assigned by EGYM and matches the identifier used in the EGYM backend to store your OAuth credentials. Contact your EGYM integration team if you are unsure of your alias.


## Handling the Absent Token

Your MWA **must** handle the case where `partnerTokens` is absent or empty. This happens when:

- The member has not linked their partner account.
- The feature flag is off or the MWA is not on the allowlist.
- A token refresh failure occurred on the backend.


Show a clear error or empty state in these cases — do not assume the token will always be present.

## Security Guidelines

- **Do not persist the token to `localStorage`** or any other client-side storage without a security review. Tokens are short-lived and should be used in-memory only.
- Tokens are automatically refreshed by the EGYM BMA during silent re-authentication (approximately every 3 hours). A fresh token will be available the next time the MWA is opened.
- The token is scoped strictly to your MWA feature — other MWAs cannot access your partner token.


## Benefits

| Benefit | Description |
|  --- | --- |
| **No re-authentication** | Members are never prompted to log in again inside the MWA. |
| **Seamless experience** | Your MWA loads ready-to-use, with API access available immediately. |
| **Automatic token refresh** | EGYM refreshes expiring tokens transparently before injecting them. |
| **Config-driven extensibility** | Adding support for additional partners or features requires no code changes on either side. |


## Token Refresh

> **Note:** Support for Partner Token Pass-Through requires a dedicated mobile release on the EGYM BMA side. The timeline for production availability will be shared separately. In the meantime, the team is continuing with improvements and testing.


Tokens injected at MWA launch are valid for a limited time. If your MWA detects that the partner token has expired (e.g. your API returns a `401`), you can request a fresh token without reloading the MWA.

### How to Request a Token Refresh

**Step 1 — Subscribe** to receive the refreshed token:

```typescript
import { portalsSubscribe } from '@ionic/portals';

portalsSubscribe('partnerTokens', (result) => {
  const partnerTokens = JSON.parse(result.data ?? '{}') as Record<string, string>;
  const myToken = partnerTokens['<your-partner-alias>'];
  // use the refreshed token
});
```

**Step 2 — Publish** a refresh request to trigger the native app to fetch a new token:

```typescript
import { publish } from '@ionic/portals';

publish({
  topic: 'subscription',
  data: {
    type: 'partnerTokens',
    data: null,
  },
});
```

The native BMA will fetch a fresh token from the EGYM backend and deliver it to MWA via the `partnerTokens` subscription.

> Make sure to set up the subscription **before** publishing the request, so you don't miss the response.


## Coordination with EGYM

To enable Partner Token Pass-Through for your MWA, work with your EGYM integration team to:

1. Confirm your **partner alias** used in EGYM .
2. Have EGYM configure your MWA feature with `passPartnerTokens = true` and `partnerTokenAliases = ["<your-alias>"]`.
3. Verify your OAuth token TTL with EGYM — very long-lived tokens (e.g., 1 day) may be subject to additional review.


For questions, contact EGYM team or refer to the [Integration API documentation](/mwa/docs/native_interface_and_plugins).