Embedded Widget Auth

Validate an existing TCM auth token from your backend before loading a hosted widget or iframe inside your site.

Local portal docs

Use this guide when:

your site already has a TCM-authenticated user
you want to host a TCM widget or app inside your own website
your backend needs to validate a TCM auth token before creating a local session or trusting the embedded user

Summary

If you already have a TCM session token, your backend can validate it against Portal.Service with:

POST /oauth/external-club/session/resolve

This is the simplest server-to-server validation flow for hosted widget integrations.

Base URLs

Production:

https://www.thecrimsonmarket.com

Development:

https://dev.portal.raum.au

The tenant path for these integrations is:

mana

In practice:

non-tenant endpoint example: https://www.thecrimsonmarket.com/oauth/external-club/session/resolve
tenant endpoint example: https://www.thecrimsonmarket.com/mana/oauth/external-club/session/resolve
dev tenant endpoint example: https://dev.portal.raum.au/mana/oauth/external-club/session/resolve

When to use this flow

Use this flow if:

a TCM token is already available in your integration
your embedded experience cannot rely only on postMessage
your backend wants to resolve the TCM user before allowing access to a widget-specific local session

Do not call this endpoint directly from the browser. Keep your OAuth client secret on your server.

Prerequisites

An active OAuth client in the Developers portal
The external_club scope enabled on that client
A linked external-club user mapping for the person using the widget
Your OAuth clientId and clientSecret stored server-side

If you still need to provision or link partner users first, use External Club Integration.

Validation request

Endpoint

POST /oauth/external-club/session/resolve

Tenant-prefixed deployments may also expose:

POST /:uiName/oauth/external-club/session/resolve

For your current environments, that tenant-prefixed route is:

POST /mana/oauth/external-club/session/resolve

Authentication

Use HTTP Basic auth with your OAuth client credentials:

clientId
clientSecret

Request body

{
  "token": "tcm_user_token"
}

What `Portal.Service` checks

the token signature is valid
the token is not expired
the token resolves to a real TCM user
that user is still linked to the same external-club OAuth client making the request

If any of those checks fail, the token should be treated as unusable for your widget session.

Success response

{
  "userId": "portal-user-id",
  "userName": "partner_member",
  "email": "[email protected]",
  "externalClub": {
    "clubName": "partnerclub",
    "externalUserId": "partner-user-123",
    "hubClubId": "hub-3456",
    "oauthClientId": "tcm_xxx"
  }
}

Use this response to decide whether to create or refresh your own local session for the embedded widget user.

Example server request

const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");

const response = await fetch(`https://www.thecrimsonmarket.com/mana/oauth/external-club/session/resolve`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: tcmSessionToken,
  }),
});

if (!response.ok) {
  throw new Error("TCM token validation failed");
}

const user = await response.json();

Recommended hosted-widget flow

Your site obtains or receives the TCM token for the current user.
Your backend sends that token to POST /oauth/external-club/session/resolve.
Portal.Service returns the resolved TCM user if the token is valid for your client.
Your backend creates or refreshes its own widget-local session.
Your page loads the iframe or widget using that validated local session.

Welcome to The Crimson Market Developers Portal

TCM OAuth Integration Docs