Magic Link - Leaf Documentation

Magic Link generates shareable URLs that give your users access to Leaf’s provider connection or file upload flows, without requiring you to embed any widget code. Send the link via email, SMS, or in-app notification. The link controls the entire authentication or upload experience and can be customized with your branding.

Link types

There are three types of Magic Links: Provider (multiple providers) lets the user connect to any of your enabled providers in one session. Requires provider app info to be registered with Leaf first (same setup as Leaf Link). Authentication (single provider) restricts the flow to one specific provider. Useful when you know which provider the user needs to connect. File Upload lets the user upload .zip files containing machine data for processing.

Creating a Magic Link

Each link type has its own creation endpoint under https://api.withleaf.io/services/widgets/api.

With an existing Leaf user

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"settings": {"companyName": "Acme Ag", "companyLogo": "https://example.com/logo.svg"}}' \
  'https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/provider'

import requests

TOKEN = "YOUR_TOKEN"
leaf_user_id = "your-leaf-user-id"
endpoint = f"https://api.withleaf.io/services/widgets/api/magic-link/users/{leaf_user_id}/provider"
headers = {"Authorization": f"Bearer {TOKEN}"}
data = {
    "settings": {
        "companyName": "Acme Ag",
        "companyLogo": "https://example.com/logo.svg"
    }
}

response = requests.post(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const leafUserId = "your-leaf-user-id";
const endpoint = `https://api.withleaf.io/services/widgets/api/magic-link/users/${leafUserId}/provider`;
const headers = { Authorization: `Bearer ${TOKEN}` };
const data = {
  settings: {
    companyName: "Acme Ag",
    companyLogo: "https://example.com/logo.svg"
  }
};

axios.post(endpoint, data, { headers }).then(res => console.log(res.data));

With automatic Leaf user creation

You can also create a Magic Link without specifying a leafUserId. In that flow, Leaf creates or reuses the Leaf user as part of link creation based on the external ID you provide:

POST /magic-link/provider
POST /magic-link/authentication
POST /magic-link/file-upload

Endpoints

Action	Method	Path
List provider links	GET	`/magic-link/provider`
Get provider link	GET	`/magic-link/provider/{magicLinkId}`
Create provider link (existing user)	POST	`/magic-link/users/{leafUserId}/provider`
Create provider link (new user)	POST	`/magic-link/provider`
Delete provider link	DELETE	`/magic-link/provider/{magicLinkId}`
List authentication links	GET	`/magic-link/authentication`
Get authentication link	GET	`/magic-link/authentication/{magicLinkId}`
Create authentication link (existing user)	POST	`/magic-link/users/{leafUserId}/authentication`
Create authentication link (new user)	POST	`/magic-link/authentication`
Delete authentication link	DELETE	`/magic-link/authentication/{magicLinkId}`
List file upload links	GET	`/magic-link/file-upload`
Get file upload link	GET	`/magic-link/file-upload/{magicLinkId}`
Create file upload link (existing user)	POST	`/magic-link/users/{leafUserId}/file-upload`
Create file upload link (new user)	POST	`/magic-link/file-upload`
Delete file upload link	DELETE	`/magic-link/file-upload/{magicLinkId}`

Customization

All Magic Link creation endpoints accept a settings object for branding:

Setting	Type	Description
`backgroundColor`	String	Background color of the link page
`companyLogo`	String	URL to your company logo
`companyName`	String	Your company name
`headerImage`	String	URL for a header image
`showLeafUserName`	Boolean	Display the Leaf user name
`disconnectEnabled`	Boolean	Allow users to disconnect providers from the link page

What to do next

Leaf Link for embedding widgets directly in your application.
Leaf Connect for sharing data between API owners.
Magic Link API Reference for full endpoint details.

​Link types

​Creating a Magic Link

​With an existing Leaf user

​With automatic Leaf user creation

​Endpoints

​Customization

​What to do next