Install @crimsoncorp/oauth-react, wire the required app-side routes, and choose the integration surface that matches your app.

1. Install the package

npm install @crimsoncorp/oauth-react

Optional styles:

import "@crimsoncorp/oauth-react/styles.css";

2. Minimum prerequisites

• A callback route on your app origin. Recommended path: /auth/tcm/callback.
• A server exchange endpoint. Default route-backed path: /api/auth/tcm/oauth-exchange.
• A client registered in the Developers portal with exact callback URLs and a server-kept client secret.
• A server-backed app. Portal.Service still requires client_secret for token exchange.

Register your client and redirect URIs in OAuth App Setup.

3. Configure environment variables

New apps need these four variables:

NEXT_PUBLIC_TCM_CLIENT_ID=tcm_xxx
TCM_OAUTH_CLIENT_SECRET=your-secret
TCM_OAUTH_API_URL=https://www.thecrimsonmarket.com/mana
NEXT_PUBLIC_TCM_OAUTH_WEB_URL=https://www.thecrimsonmarket.com

Use the same NEXT_PUBLIC_TCM_CLIENT_ID in the browser hook and the server exchange route. No separate server-only client ID or redirect URI environment variable is required for the standard SDK flow.

4. Choose your integration surface

Recommended

Use useTcmOAuth, TcmOAuthCallbackPage, and createTcmOAuthExchangeRoute.

Best for server-backed React and Next.js apps. It supports automatic popup vs redirect selection and popup-blocked fallback.

Continue with React Quickstart or Next.js Server Flow.

Compatibility popup path

Use useTcmOAuthPopupRoute when preserving a popup-only flow or an older callback contract.

Default compatibility callback path remains /auth/tcm/popup-callback.

Advanced or low-level

Use useTcmOAuthPopup, createTcmOAuthClient, createTcmOAuthRouteClient, and server helpers when you need custom exchange handling.

See API Reference.

5. What happens after install

• The route-backed flow uses the explicit scope requested by the app, or the single allowed client scope when only one scope is configured.
• interactionMode="auto" chooses popup on desktop-like environments and redirect on mobile-like environments.
• If redirect is used, the callback handler stores the result and resumes at the initiating route using returnTo when present.
• Diagnostics headers are sent in auto mode for development and staging-like environments.