Magic Link

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.

Link token API

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
}

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:

2. Include callback_url in link token request

Add a callback_url parameter to your link token request body:

1
POST /registered-users/{id}/link-token
2
3
{
4
  "connector_slug": "linear",
5
  "callback_url": "https://myapp.com/integrations/done"
6
}

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 request will fail with a validation error.

3. Handle the redirect

After the user completes (or exits) the authentication flow, they are redirected to your callback URL. Merge automatically appends query parameters to indicate the result. These parameters are added by Merge during the redirect — you don’t need to include them in your callback URL.

The following parameters are appended to your callback URL:

Status values:

Example redirect URLs:

Basic flow (credential created immediately):

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

Secure flow with authorization code (when state is provided):

https://myapp.com/integrations/done?status=success&code=ah_code_xyz789...&state=custom-value

Mobile deep link example

Register your app’s custom URL scheme as an allowed origin (myapp://), then include it in your link token request:

1
POST /registered-users/{id}/link-token
2
3
{
4
  "connector_slug": "linear",
5
  "callback_url": "myapp:///integrations/complete"
6
}

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

Authorization Code Exchange

Use server-to-server code exchange instead of creating credentials immediately in the browser. This adds an extra security layer by letting your backend verify the credential belongs to the right user before it’s saved.

How it works:

1. Include a state parameter when calling POST /registered-users/{id}/link-token
2. User authenticates and is redirected to your callback URL with a code and state
3. Your backend exchanges the code for a credential via POST /api/v1/link-token/confirm/

Create a link token with state

Include both state and callback_url when creating a link token:

1
POST /registered-users/{id}/link-token
2
3
{
4
  "connector_slug": "linear",
5
  "callback_url": "https://myapp.com/integrations/callback",
6
  "state": "random-csrf-token-123"
7
}

The response includes the magic link URL:

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

Receive the authorization code

After authentication completes, your callback URL receives the code:

https://myapp.com/integrations/callback?status=success&code=ah_code_xyz789...&state=random-csrf-token-123

Always validate that the state parameter matches your original value to prevent CSRF attacks.

Exchange the code

Call the confirmation endpoint from your backend:

1
POST /api/v1/link-token/confirm/
2
Authorization: ProductionKey <your-production-key>
3
Content-Type: application/json
4
5
{
6
  "code": "ah_code_xyz789..."
7
}

Response:

1
{
2
  "credential_id": "134e0111-0f67-44f6-98f0-597000290bb3",
3
  "connector_slug": "linear",
4
  "registered_user_id": "550e8400-e29b-41d4-a716-446655440000"
5
}

The credential is created and ready. The code is deleted after exchange.

Security

• Codes expire after 5 minutes — exchange them promptly
• Each code can only be exchanged once
• The confirm endpoint requires ProductionKey authentication
• Codes can only be exchanged by the organization that created them
• Always validate the state parameter matches your original value

Error handling

When to use

Use authorization code exchange when you need server-to-server credential creation for security or compliance requirements, or when building mobile/desktop apps with a backend.

For simpler flows where the user authenticates and closes the tab, omit the state parameter — credentials are created immediately.