MediaValet + Marq Deep Links: Authentication & Template Linking Guide

Overview

This guide explains how to configure deep links from a MediaValet Beam portal that direct users into a specific Marq template — and how authentication is handled along the way. Two paths exist depending on who acts as the Identity Provider (IdP): MediaValet itself, or a separate SAML provider of the customer's choosing.

Authentication Paths at a Glance

Which path is right for you?

• We use MediaValet as our SSO provider → Use Path A. No extra SAML configuration needed in Marq.
• We manage identities through Okta, Azure AD, Google, or another provider → Use Path B. You'll configure SAML directly in Marq.

Path A — MediaValet as the Identity Provider (IdP)

When MediaValet is configured as the IdP, Marq uses a dedicated login endpoint that checks existing session state before acting — keeping the experience as friction-free as possible for end users.

How it works:

1. User clicks a deep link in the Beam portal. The link points to the Marq /users/mediavaletLogin endpoint, with the target template URL passed as a URL-encoded returnUrl parameter.
2. Marq checks for an existing session. If the user is already logged in to Marq, they are passed directly to the destination. No login prompt is shown.
3. If not authenticated — MediaValet SSO login. The user is redirected to the MediaValet login page. Once authenticated, they're sent on to the template destination.
4. New user? Automatic provisioning. If the user doesn't yet have a Marq account, one is created automatically — provided they have the appropriate Marq app permissions assigned in MediaValet.

ℹ️ Note: This works automatically for any Marq account already configured with MediaValet as the IdP. No feature flag or additional Marq team enablement is required. If an account is not set up for MediaValet SSO, the endpoint redirects to the standard Marq login page with an error.

Setup steps:

1. Configure SSO with MediaValet as the IdP using the standard MediaValet SSO process.
2. The MediaValet team must provide the OrgId so it can be mapped to the correct Marq account.
3. Ensure users have the Marq app permission assigned in MediaValet so they can be auto-provisioned.
4. Build deep links using the format in the "Building Deep Links" section below and embed them in your Beam portal.

Path B — Custom SAML (Bring Your Own IdP)

If your organization uses a different identity provider (Okta, Azure AD, Google Workspace, etc.), you can configure SAML directly in Marq and bypass MediaValet as the IdP entirely.

⚠️ Important: This path does not provide the seamless session sharing between MediaValet and Marq that Path A offers. Users will have separate authenticated sessions in each product and may be prompted to log in to Marq independently.

How it works:

1. User clicks a deep link in the Beam portal. The link points directly to the Marq template URL.
2. Marq detects the user is unauthenticated and redirects them to your configured SAML IdP.
3. User authenticates via your IdP. SAML asserts their identity back to Marq on success.
4. User is sent to the template destination. Marq resumes the original URL.

Setup steps:

1. Complete the Marq SAML/SCIM configuration using the Marq SAML & SCIM Overview (linked below).
2. Enable SCIM or JIT provisioning to ensure users are created in Marq automatically on first login.
3. Build deep links pointing directly to Marq template URLs and embed them in your Beam portal. No /users/mediavaletLogin prefix is needed — SAML handles unauthenticated requests automatically.

Building Deep Links to Marq Templates

Path A — MediaValet IdP link format:

https://app.marq.com/users/mediavaletLogin?returnUrl=<URL-encoded destination>

Example:

https://app.marq.com/users/mediavaletLogin?returnUrl=https%3A%2F%2Fapp.marq.com%2Fdocuments%2FeditNew%2F1e4b4ecc-309c-42ac-b497-a2f2343a640f

⚠️ The returnUrl value must be URL-encoded. Use a URL encoder or your platform's built-in encoding function when building these links programmatically.

Path B — Direct template URL formats:

https://app.marq.com/documents/editNew/<template-id>   ← creates a new document from the template https://app.marq.com/documents/edit/<template-id>      ← opens an existing document

The template ID is the UUID in the URL when you open a template in Marq. See the Marq Template Links Guide for a full breakdown of available link types.

Frequently Asked Questions

Does /users/mediavaletLogin require a feature flag or special setup by the Marq team? No. It works automatically for any Marq account configured with MediaValet as the IdP. If the account isn't set up for MediaValet SSO, the endpoint redirects to the standard Marq login with an error.

Does the returnUrl parameter need to be URL-encoded? Yes. https://app.marq.com/documents/editNew/abc123 becomes https%3A%2F%2Fapp.marq.com%2Fdocuments%2FeditNew%2Fabc123. Most platforms and languages include a built-in function for this.

What happens if a user doesn't have a Marq account yet (Path A)? A Marq account is automatically created when they first authenticate — as long as they have the Marq app permission assigned in MediaValet.

Why is an OrgId required for Path A, and who provides it? The OrgId maps the MediaValet organization to the correct Marq account. The MediaValet team provides this value during integration setup.

Can a customer use Path B even if MediaValet is their IdP? Yes, but it's not recommended. It removes the seamless session sharing between products, requiring users to authenticate into Marq separately.

Will users always be prompted to log in when clicking a deep link? On Path A, no. The endpoint checks for an active session first. Already-authenticated users are passed straight through to their destination.

Reference Links

• Marq Template Links Guide
• Marq SAML & SCIM Overview
• MediaValet Login Endpoint