OAuth Integration Guide

MRC Connect uses OAuth 2.1 Authorization Code flow with PKCE to let your application send and manage compliance-grade texting through MyRepChat on behalf of an advisor. This guide assumes FMG has provisioned your application.

MRC and FMG are separate integrations. This guide covers MRC (mrc.* scopes) with its own Client ID/Secret. For FMG contacts/content, see the FMG APIs → OAuth guide. If you integrate both, you run this flow once per product — two client credentials, two consents, two tokens.

The MRC APIs are not yet available. The OAuth integration below is ready to use; API endpoints, scopes, and the API base URL will be published when the MRC APIs are released.

What FMG provides

FMG provisions your MRC application per environment — sandbox first, then production. Build and test against sandbox, then repeat with the production values.

Item	Sandbox	Production
Client ID	Issued by FMG (sandbox)	Issued by FMG (production)
Client Secret	Issued by FMG — server-side only	Issued by FMG — server-side only
Authorize URL	`https://connect.myrepchat.com/oauth/authorize`	`https://connect.myrepchat.com/oauth/authorize`
Token URL	`https://oauth.fmgsuite.com/v1/oauth2/token`	`https://oauth.fmgsuite.com/v1/oauth2/token`
API Base URL	Provided at onboarding	Provided at onboarding
Scopes	The `mrc.*` scopes granted to your app (see Scopes)	Same

The OAuth endpoints (oauth.fmgsuite.com) are shared across environments, but the Client ID and Secret differ between sandbox and production — use each set only with the environment it was issued for.

What you provide

You give FMG one thing up front:

Item	Description
Redirect URI(s)	The exact callback URL(s) in your app where FMG returns the authorization `code`. Provide one per environment (e.g. `https://app.example.com/callback` for production, `https://staging.example.com/callback` for sandbox).

FMG registers these in its OAuth service (Stytch) against your MRC Client ID. Only registered URIs are accepted at authorization time.

Why the redirect URI matters

The redirect URI is the most security-critical value you register, because it is where the authorization code is delivered:

After the advisor approves consent, the authorization server sends the browser to redirect_uri?code=.... Whoever controls that URL receives the code and can exchange it for tokens.
So the authorization server treats your registered URIs as a strict allowlist: the redirect_uri in the authorize request must match a registered URI exactly — scheme, host, port, and path. A mismatch is rejected before any code is issued.
This closes authorization-code interception / open-redirect attacks — an attacker can’t substitute their own callback to capture the code, because an unregistered URI never matches.
It must be HTTPS and a URL your server controls (no wildcards, no fragments). Register every environment’s callback, since sandbox and production use different values.

PKCE (Step 1) protects the code in transit; exact redirect-URI matching ensures the code is only ever sent to you. Both are required.

Flow at a glance

Generate PKCE + state

Server-side, create a code_verifier, its code_challenge (S256), and a random state.

Redirect to authorize

Send the advisor’s browser to the Authorize URL with your request parameters.

Handle the callback

FMG redirects back with code and state. Validate state.

Exchange code for tokens

Server-side POST to the Token URL with the code, code_verifier, and client_secret.

Call MRC APIs

Use the access_token as a Bearer token. Refresh it when it expires.

Step 1 — Generate PKCE parameters

Generate these on your server and store code_verifier + state in the user’s server-side session:

code_verifier  = base64url(random(32 bytes))   // 43-char string
code_challenge = base64url(SHA256(code_verifier))
state          = base64url(random(16 bytes))

Step 2 — Redirect to authorization

Redirect the advisor’s browser to the Authorize URL:

GET https://connect.myrepchat.com/oauth/authorize
  &response_type=code
  &client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &code_challenge={code_challenge}
  &code_challenge_method=S256
  &state={state}
  &scope={SCOPES}

Parameter	Required	Value
`response_type`	Yes	`code`
`client_id`	Yes	Your MRC Client ID
`redirect_uri`	Yes	Must exactly match a registered URI
`code_challenge`	Yes	S256 challenge from Step 1
`code_challenge_method`	Yes	`S256`
`state`	Yes	Random CSRF value from Step 1
`scope`	Yes	Space-separated `mrc.*` scopes assigned by FMG

The advisor authenticates and approves a consent screen listing your requested permissions.

Step 3 — Handle the callback

FMG redirects to your redirect_uri:

GET {REDIRECT_URI}?code={authorization_code}&state={state}

In your handler:

Compare state against the session value — abort on mismatch (CSRF).
Retrieve the code_verifier from the session.
Clear both from the session — they are single-use.

Step 4 — Exchange the code for tokens

Server-side POST to the Token URL. Authenticate with your client_secret:

curl -X POST https://oauth.fmgsuite.com/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code={authorization_code} \
  -d client_id={CLIENT_ID} \
  -d client_secret={CLIENT_SECRET} \
  -d code_verifier={code_verifier} \
  -d redirect_uri={REDIRECT_URI}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "v2.abc...",
  "scope": "openid offline_access"
}

The refresh_token is only returned when the offline_access scope is granted. Store both tokens securely (server-side session or HttpOnly cookie — never localStorage).

Step 5 — Call MRC APIs

The MRC APIs are not yet available. When released, you will call them with the access token as a Bearer token (Authorization: Bearer {access_token}); their endpoints and required scopes will be documented under MRC APIs → API Reference.

Step 6 — Refresh the access token

When the access token expires (401 response), use the refresh token to get a new one without sending the advisor through the flow again:

curl -X POST https://oauth.fmgsuite.com/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token={refresh_token} \
  -d client_id={CLIENT_ID} \
  -d client_secret={CLIENT_SECRET}

Scopes

Request exactly the scopes FMG assigned you — requesting an unprovisioned scope fails.

Scope	Grants
`openid`	Required — identity claims in the token.
`offline_access`	Returns a refresh token for long-lived access.

MRC API scopes (for sending SMS, reading delivery status, and similar operations) are not yet available and will be published here when the MRC APIs are released. The flow currently issues identity scopes only (openid, offline_access).

Errors

Situation	Result
User denies consent	Redirect to `redirect_uri` with `error=access_denied`.
`state` mismatch	Reject the callback — possible CSRF.
Invalid / expired code	Token exchange returns `400`.
`code_verifier` mismatch	Token exchange returns `400`.
Expired access token	API returns `401` — refresh the token (Step 6).
Expired refresh token	Refresh returns `400` — restart from Step 2.
MRC unavailable	`503` — transient; retry after a short delay.

Security requirements

PKCE (S256) for every request; keep the code_verifier server-side.
Unique state per request; validate on callback.
Token exchange and refresh are server-side only — never expose client_secret or code_verifier to the browser.
HTTPS for all redirect URIs and API calls.
Store tokens in HttpOnly cookies or server-side sessions.

​What FMG provides

​What you provide

​Why the redirect URI matters

​Flow at a glance

​Step 1 — Generate PKCE parameters

​Step 2 — Redirect to authorization

​Step 3 — Handle the callback

​Step 4 — Exchange the code for tokens

​Step 5 — Call MRC APIs

​Step 6 — Refresh the access token

​Scopes

​Errors

​Security requirements

What FMG provides

What you provide

Why the redirect URI matters

Flow at a glance

Step 1 — Generate PKCE parameters

Step 2 — Redirect to authorization

Step 3 — Handle the callback

Step 4 — Exchange the code for tokens

Step 5 — Call MRC APIs

Step 6 — Refresh the access token

Scopes

Errors

Security requirements