Skip to main content
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. 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. 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'

​
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

ActionMethodPath
List provider linksGET/magic-link/provider
Get provider linkGET/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 linkDELETE/magic-link/provider/{magicLinkId}
List authentication linksGET/magic-link/authentication
Get authentication linkGET/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 linkDELETE/magic-link/authentication/{magicLinkId}
List file upload linksGET/magic-link/file-upload
Get file upload linkGET/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 linkDELETE/magic-link/file-upload/{magicLinkId}

​
Customization

All Magic Link creation endpoints accept a settings object for branding:
SettingTypeDescription
backgroundColorStringBackground color of the link page
companyLogoStringURL to your company logo
companyNameStringYour company name
headerImageStringURL for a header image
showLeafUserNameBooleanDisplay the Leaf user name
disconnectEnabledBooleanAllow users to disconnect providers from the link page

​
What to do next

Last modified on March 24, 2026