Skip to main content
Use the Magic Link endpoints to create hosted authentication or file-upload flows that you can send directly to end users. This page covers the provider, single-provider authentication, and file-upload link variants, along with the settings object they share. For conceptual background, see Magic Link.

​
Overview

Magic Links are shareable URLs that let your users connect provider accounts or upload files without embedding widgets in your application. There are three types:
  • Provider — multi-provider authentication (connect one or more providers).
  • Authentication — single-provider authentication (connect exactly one provider).
  • File Upload — manual file upload through a hosted interface.
Base URL: https://api.withleaf.io/services/widgets/api
All Magic Link types share the same expiresIn parameter: lifetime in seconds, minimum 900, maximum approximately 1 year.
The GET endpoints return usage-tracking fields such as usageCount and maxUsage. Magic Links are not inherently single-use.

​
Settings object

Every Magic Link type accepts an optional settings object to customize the hosted page:
FieldTypeDescription
backgroundColorstringHex color for the page background.
headerImagestringURL of an image displayed in the header.
companyLogostringURL of your company logo.
companyNamestringYour company name displayed on the page.
showLeafUserNamebooleanWhether to display the Leaf user’s name.
disconnectEnabledbooleanWhether the user can disconnect a provider.
Lets the end user authenticate with multiple providers in a single session.

​
Endpoints

EndpointMethodPath
Get allGET/magic-link/provider
Get oneGET/magic-link/provider/{magicLinkId}
Create (with Leaf user)POST/magic-link/users/{leafUserId}/provider
Create (with auto Leaf user)POST/magic-link/provider
DeleteDELETE/magic-link/provider/{magicLinkId}
POST /magic-link/users/{leafUserId}/provider Creates a Magic Link for an existing Leaf user.

​
Path parameters

ParameterTypeRequiredDescription
leafUserIdstringYesThe UUID of the Leaf user.

​
Request body

FieldTypeRequiredDescription
expiresInintegerNoLifetime in seconds. Min 900, max ~1 year.
allowedProvidersstring[]NoProvider keys to display (e.g. "JohnDeere", "ClimateFieldView").
settingsobjectNoCustomization options. See Settings object.
curl -X POST \
  "https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/provider" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresIn": 604800,
    "allowedProviders": ["JohnDeere", "ClimateFieldView"],
    "settings": {
      "backgroundColor": "#ffffff",
      "companyName": "Acme Ag",
      "disconnectEnabled": true
    }
  }'

​
Response

{
  "id": "magicLinkId",
  "leafUserId": "UUID",
  "link": "https://magic-link.withleaf.io/{magicLinkId}",
  "expiresAt": "2024-10-26T14:23:56.584Z"
}
POST /magic-link/provider Creates a Magic Link for flows where Leaf creates a Leaf user based on the provided externalId.

​
Request body

FieldTypeRequiredDescription
externalIdstringYesYour identifier for the user. Required for automatic Leaf user creation.
namestringNoDisplay name for the auto-created Leaf user.
emailstringNoEmail for the auto-created Leaf user.
expiresInintegerNoLifetime in seconds. Min 900, max ~1 year.
allowedProvidersstring[]NoProvider keys to display.
settingsobjectNoCustomization options. See Settings object.
curl -X POST \
  "https://api.withleaf.io/services/widgets/api/magic-link/provider" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "farmer-123",
    "name": "Jane Doe",
    "expiresIn": 604800,
    "allowedProviders": ["JohnDeere"]
  }'
GET /magic-link/provider Returns all Provider Magic Links for your API owner.

​
Query parameters

ParameterTypeRequiredDescription
nextPageTokenstringNoPagination token returned by a previous list response. Use 0 or omit it for the first page.
curl -X GET \
  "https://api.withleaf.io/services/widgets/api/magic-link/provider" \
  -H "Authorization: Bearer {token}"

​
Response

{
  "items": [
    {
      "id": "magicLinkId",
      "link": "https://magic-link.withleaf.io/{magicLinkId}",
      "createdAt": "2024-10-19T14:23:56.584Z",
      "expiresAt": "2024-10-26T14:23:56.584Z",
      "lastAccessedAt": "2024-10-19T14:23:56.584Z",
      "leafUserId": "UUID",
      "maxUsage": 3,
      "usageCount": 0,
      "widget": "PROVIDER",
      "allowedProviders": ["JohnDeere", "ClimateFieldView"],
      "settings": {
        "companyName": "Acme Ag",
        "companyLogo": "https://example.com/logo.svg",
        "disconnectEnabled": true
      }
    }
  ],
  "nextPageToken": "opaque-pagination-token"
}
GET /magic-link/provider/{magicLinkId} Returns a single Provider Magic Link by ID.

​
Path parameters

ParameterTypeRequiredDescription
magicLinkIdstringYesThe ID of the Magic Link.

​
Response

{
  "id": "magicLinkId",
  "link": "https://magic-link.withleaf.io/{magicLinkId}",
  "createdAt": "2024-10-19T14:23:56.584Z",
  "expiresAt": "2024-10-26T14:23:56.584Z",
  "lastAccessedAt": "2024-10-19T14:23:56.584Z",
  "leafUserId": "UUID",
  "maxUsage": 3,
  "usageCount": 0,
  "widget": "PROVIDER",
  "allowedProviders": ["JohnDeere", "ClimateFieldView"],
  "settings": {
    "companyName": "Acme Ag",
    "companyLogo": "https://example.com/logo.svg",
    "disconnectEnabled": true
  }
}
DELETE /magic-link/provider/{magicLinkId} Permanently deletes a Provider Magic Link. The URL immediately stops working.

​
Path parameters

ParameterTypeRequiredDescription
magicLinkIdstringYesThe ID of the Magic Link.
Lets the end user authenticate with a single, specified provider.

​
Endpoints

EndpointMethodPath
Get allGET/magic-link/authentication
Get oneGET/magic-link/authentication/{magicLinkId}
Create (with Leaf user)POST/magic-link/users/{leafUserId}/authentication
Create (with auto Leaf user)POST/magic-link/authentication
DeleteDELETE/magic-link/authentication/{magicLinkId}
POST /magic-link/users/{leafUserId}/authentication Creates a Magic Link scoped to a single provider for an existing Leaf user.

​
Path parameters

ParameterTypeRequiredDescription
leafUserIdstringYesThe UUID of the Leaf user.

​
Request body

FieldTypeRequiredDescription
expiresInintegerNoLifetime in seconds. Min 900, max ~1 year.
providerstringYesThe provider key (e.g. "JohnDeere", "ClimateFieldView").
settingsobjectNoCustomization options. See Settings object.
curl -X POST \
  "https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/authentication" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresIn": 604800,
    "provider": "JohnDeere",
    "settings": {
      "companyName": "Acme Ag"
    }
  }'

​
Response

{
  "id": "magicLinkId",
  "leafUserId": "UUID",
  "link": "https://magic-link.withleaf.io/{magicLinkId}",
  "expiresAt": "2024-10-26T14:23:56.584Z"
}
POST /magic-link/authentication Creates a Magic Link for flows where Leaf creates a Leaf user based on the provided externalId.

​
Request body

FieldTypeRequiredDescription
externalIdstringYesYour identifier for the user.
namestringNoDisplay name for the auto-created Leaf user.
emailstringNoEmail for the auto-created Leaf user.
expiresInintegerNoLifetime in seconds. Min 900, max ~1 year.
providerstringYesThe provider key.
settingsobjectNoCustomization options. See Settings object.
Use the auto-create variant when you do not want to create the Leaf user separately before sending the link.

​
Get, Delete

The Get all, Get one, and Delete endpoints for Authentication Magic Links follow the same pattern as the Provider Magic Link endpoints, but the resource includes a single provider field instead of allowedProviders. Authentication list endpoints also use the same paginated envelope with items and nextPageToken.

​
Authentication list/get response shape

{
  "id": "magicLinkId",
  "link": "https://magic-link.withleaf.io/{magicLinkId}",
  "createdAt": "2024-10-19T14:23:56.584Z",
  "expiresAt": "2024-10-26T14:23:56.584Z",
  "lastAccessedAt": "2024-10-19T14:23:56.584Z",
  "leafUserId": "UUID",
  "maxUsage": 3,
  "usageCount": 0,
  "widget": "AUTHENTICATION",
  "provider": "JohnDeere",
  "settings": {
    "companyName": "Acme Ag",
    "companyLogo": "https://example.com/logo.svg"
  }
}
Lets the end user upload machine files through a hosted interface.

​
Endpoints

EndpointMethodPath
Get allGET/magic-link/file-upload
Get oneGET/magic-link/file-upload/{magicLinkId}
Create (with Leaf user)POST/magic-link/users/{leafUserId}/file-upload
Create (with auto Leaf user)POST/magic-link/file-upload
DeleteDELETE/magic-link/file-upload/{magicLinkId}
POST /magic-link/users/{leafUserId}/file-upload Creates a Magic Link for uploading machine files, tied to an existing Leaf user.

​
Path parameters

ParameterTypeRequiredDescription
leafUserIdstringYesThe UUID of the Leaf user.

​
Request body

FieldTypeRequiredDescription
expiresInintegerNoLifetime in seconds. Min 900, max ~1 year.
settingsobjectNoCustomization options. See Settings object.
curl -X POST \
  "https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/file-upload" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresIn": 604800,
    "settings": {
      "companyName": "Acme Ag",
      "companyLogo": "https://example.com/logo.png"
    }
  }'

​
Response

{
  "id": "magicLinkId",
  "leafUserId": "UUID",
  "link": "https://magic-link.withleaf.io/{magicLinkId}",
  "expiresAt": "2024-10-26T14:23:56.584Z"
}
POST /magic-link/file-upload Creates a Magic Link for flows where Leaf creates a Leaf user based on the provided externalId.

​
Request body

FieldTypeRequiredDescription
externalIdstringYesYour identifier for the user.
namestringNoDisplay name for the auto-created Leaf user.
emailstringNoEmail for the auto-created Leaf user.
expiresInintegerNoLifetime in seconds. Min 900, max ~1 year.
settingsobjectNoCustomization options. See Settings object.

​
Get, Delete

The Get all, Get one, and Delete endpoints for File Upload Magic Links follow the same paginated pattern as the Provider Magic Link endpoints. File Upload list endpoints also use the same paginated envelope with items and nextPageToken.

​
File Upload list/get response shape

{
  "id": "magicLinkId",
  "link": "https://magic-link.withleaf.io/{magicLinkId}",
  "createdAt": "2024-10-19T14:23:56.584Z",
  "expiresAt": "2024-10-26T14:23:56.584Z",
  "lastAccessedAt": "2024-10-19T14:23:56.584Z",
  "leafUserId": "UUID",
  "maxUsage": 3,
  "usageCount": 0,
  "widget": "FILE_UPLOAD",
  "settings": {
    "companyName": "Acme Ag",
    "companyLogo": "https://example.com/logo.svg"
  }
}
Last modified on March 24, 2026