> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Magic Link

> Generate shareable URLs that let growers connect their provider accounts or upload machine files without building a custom authentication UI.

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](/components/leaf-link#provider-setup)).

**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

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

### 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](/components/leaf-link) for embedding widgets directly in your application.
* [Leaf Connect](/components/leaf-connect) for sharing data between API owners.
* [Magic Link API Reference](/api-reference/magic-link) for full endpoint details.