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 flow below issues the access token you use to call the MRC messaging APIs. Once you have a token, continue with the Integration Guide and the API Reference.

What FMG provides

FMG provisions your MRC application with the following values.

Item	Value
Client ID	Issued by FMG
Client Secret	Issued by FMG — server-side only
Authorize URI	`https://dart.ionlake.com/oauth/authorize`
Token URI	`https://oauth.fmgsuite.com/v1/oauth2/token`
API Base URI	`https://connect.fmgsuite.com`
API key	Issued by FMG — sent as the `x-api-key` header on every API request
Scopes	The `mrc.*` scopes granted to your app (see Scopes)

What you provide

You give FMG one thing up front:

Item	Description
Redirect URI(s)	The exact callback URI(s) in your app where FMG returns the authorization `code` (e.g. `https://app.example.com/callback`).

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 URI 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 URI your server controls (no wildcards, no fragments). Register every callback your application will use.

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 URI 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 URI 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 URI:

GET https://dart.ionlake.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 URI. 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 mrc.messaging.read mrc.messaging.write"
}

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).

A refresh token is valid for 90 days. Each refresh extends it by another 90 days, and the token value does not change — keep using the one you stored. A connection that refreshes at least once every 90 days stays active.

Step 5 — Call MRC APIs

Send the access token as a Bearer token, together with your x-api-key:

curl -X POST https://{API_BASE_URI}/v1/mrc/messaging/messages \
  -H "Authorization: Bearer {access_token}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+12185551234", "text": "Hi Sam — your review is confirmed for Tuesday at 2pm." }'

The Integration Guide walks the full send → consent → poll → resend loop; every endpoint and field is documented in the 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}

If the refresh token has expired (no refresh in 90 days) or the advisor has revoked access, the request returns 400 with error=invalid_grant. Send the advisor through the flow again from Step 1 to reconnect.

Scopes

Request exactly the scopes FMG assigned you — requesting an unprovisioned scope fails. If FMG grants your app a new scope later, existing advisors must re-authorize to approve it. See Adding scopes.

Scope	Grants
`openid`	Required — identity claims in the token.
`offline_access`	Returns a refresh token for long-lived access.
`mrc.messaging.write`	Send messages and send consent requests from the advisor’s MyRepChat number.
`mrc.messaging.read`	Read consent status (and delivery status, when released).

Endpoints

Method	Endpoint	Required scope
`POST`	`/v1/mrc/messaging/messages`	`mrc.messaging.write`
`POST`	`/v1/mrc/messaging/consent-requests`	`mrc.messaging.write`
`GET`	`/v1/mrc/messaging/consents`	`mrc.messaging.read`

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 or revoked refresh token	Refresh returns `400` `invalid_grant` — restart from Step 1.
Token lacks a required scope	API returns `403` `forbidden`; re-authorize (Adding scopes).
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

​Endpoints

​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

Endpoints

Errors

Security requirements