Features

Magic Link

Let your agent share a URL for users to authenticate — no frontend component needed.

Instead of embedding the Link component in a frontend, your agent can get a URL back that it shares directly with users. The user opens it in a browser, authenticates, and closes the tab.

No changes are needed on your end to start using this — the magic link URL is returned automatically.

When you call POST /registered-users/{id}/link-token, the response now includes a magic_link_url field:

1{
2  "link_token": "abc123...",
3  "magic_link_url": "https://ah-api.merge.dev/magic-link/..."
4}

Your agent can send that URL to the user however it likes — in a chat message, email, or in-app notification. The user clicks it, connects their account, and clicks “Done” to close the tab.

The link_token field still works exactly as before if you want to embed the Link component yourself.

Authenticate tools (MCP / agent tool calls)

When your agent calls an authenticate_* tool, the result payload now includes a message and magic link URL:

1{
2  "message": "The user must authenticate with Linear. Share this link with the user to connect their account: https://ah-api.merge.dev/magic-link/... Once authenticated, you must refetch tools or restart your MCP connection.",
3  "magic_link_url": "https://ah-api.merge.dev/magic-link/...",
4  "link_token": "abc123..."
5}
FieldDescription
messageAn instruction for the agent — tells it to share the link with the user and what to do after authentication.
magic_link_urlThe URL to share with the user for authentication.
link_tokenThe link token, still included for backwards compatibility with the embedded Link component.

Callback URLs

You can automatically redirect users back to your application after they complete authentication via a Magic Link. This is especially useful for mobile deep linking and desktop apps.

1. Register allowed origins

Before using callback URLs, register the allowed origins for your organization in the Merge dashboard under Settings → API keys → Allowed callback origins.

An origin is the scheme and host of your callback URL. Valid origins include:

OriginUse case
https://myapp.comWeb application
https://app.example.com:8443Web app on a custom port
myapp://Mobile deep link (iOS / Android)
tauri://Desktop app (Tauri, Electron, etc.)
HTTP origins are not allowed. Use HTTPS for web applications or a custom scheme for native apps.

2. Append the callback URL

Add a callback_url query parameter to the Magic Link URL:

https://ah-api.merge.dev/magic-link/<token>?callback_url=https://myapp.com/integrations/done

The origin of the callback_url (e.g. https://myapp.com) must match one of the origins you registered. If it doesn’t match, the redirect is silently skipped.

3. Handle the redirect

After the user completes (or exits) the authentication flow, they are redirected to your callback URL with a status query parameter:

StatusMeaning
successUser completed authentication successfully
errorAn error occurred during authentication
exitUser closed or exited the flow without completing

For example:

https://myapp.com/integrations/done?status=success

Register your app’s custom URL scheme as an allowed origin (myapp://), then pass a deep link as the callback URL:

https://ah-api.merge.dev/magic-link/<token>?callback_url=myapp:///integrations/complete

After authentication, the browser redirects to myapp:///integrations/complete?status=success, which opens your native app via its registered URL scheme.