Magic Link Endpoints

About

All HTTP methods should be prepended by this service's endpoint:

https://api.withleaf.io/services/widgets/api

Magic Link

Provider

This is a link to authenticate with multiple providers.

Endpoints

DescriptionEndpoints
Get all provider Magic LinksGET /magic-link/provider
Get a provider Magic LinkGET /magic-link/provider/{magicLinkId}
Create a provider Magic LinkPOST /magic-link/users/{leafUserId}/provider
Delete a provider Magic LinkDELETE /magic-link/provider/{magicLinkId}

Get all provider Magic Link

 GET /magic-link/provider

Get all created links for authentication across multiple providers.

Request examples
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/provider'
Response
[
{
"id": "magicLinkId",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"createdAt": "2023-11-02T19:17:16.494Z",
"expiresAt": "2024-10-26T14:23:56.584Z",
"lastAccessedAt": "2023-11-02T19:17:18.906Z",
"leafUserId": "UUID",
"maxUsage": 3,
"usageCount": 0,
"widget": "PROVIDER",
"settings": {
"backgroundColor": "codeColor",
"headerImage": "URL",
"companyLogo": "URL",
"companyName": "companyName",
"showLeafUserName": "boolean",
"disconnectEnabled": "boolean"
},
"allowedProviders": [
"Other"
]
},
....
]

Get a provider Magic Link

 GET /magic-link/provider/{magicLinkId}

Get a created link for authentication across multiple providers.

Request examples
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/provider/{magicLinkId}'
Response
{
"id": "magicLinkId",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"createdAt": "2023-11-02T19:17:16.494Z",
"expiresAt": "2024-10-26T14:23:56.584Z",
"lastAccessedAt": "2023-11-02T19:17:18.906Z",
"leafUserId": "UUID",
"maxUsage": 3,
"usageCount": 0,
"widget": "PROVIDER",
"settings": {
"backgroundColor": "codeColor",
"headerImage": "URL",
"companyLogo": "URL",
"companyName": "companyName",
"showLeafUserName": "boolean",
"disconnectEnabled": "boolean"
},
"allowedProviders": [
"Other"
]
}

Create a provider Magic Link

 POST /magic-link/users/{leafUserId}/provider

Provider application info

Make sure you set up your provider application first. More info here.

Creates a link for authentication across multiple providers.

  • allowedProviders: the list of providers allowed in the authentication process. It can be one or more of the following: JohnDeere, ClimateFieldView, CNHI, AgLeader, Trimble, RavenSlingshot, and Stara.
  • expiresIn: an integer number for the expiration time, in seconds. This parameter is optional and the default value is 900 (minimum) and the maximum is the equivalent to 1 year.
Request body
{
"expiresIn": int,
"allowedProviders": [
"providerName"
]
}
Request examples
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "expiresIn": int, "allowedProviders": ["providerName"], "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/provider'
Response
{
"id": "magicLinkId",
"leafUserId": "UUID",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"expiresAt": "2010-10-10T10:10:10.000000000Z"
}

Delete a provider Magic Link

 DELETE /magic-link/provider/{magicLinkId}

Delete a link for authentication across multiple providers.

Request examples
curl -X DELETE \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/provider/{magicLinkId}'

Authentication

This is a link to authenticate with a single provider.

Endpoints

DescriptionEndpoints
Get all authentication Magic LinksGET /magic-link/authentication
Get an authentication Magic LinkGET /magic-link/authentication/{magicLinkId}
Create an authentication Magic LinkPOST /magic-link/users/{leafUserId}/authentication
Delete an authentication Magic LinkDELETE /magic-link/authentication/{magicLinkId}

Get all authentication Magic Links

 GET /magic-link/authentication

Get all created links for authentication with a single provider.

Request examples
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/authentication'
Response
[
{
"id": "magicLinkId",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"createdAt": "2023-11-02T19:17:16.494Z",
"expiresAt": "2024-10-26T14:23:56.584Z",
"lastAccessedAt": "2023-11-02T19:17:18.906Z",
"leafUserId": "UUID",
"maxUsage": 3,
"usageCount": 0,
"widget": "AUTHENTICATION",
"settings": {
"backgroundColor": "codeColor",
"headerImage": "URL",
"companyLogo": "URL",
"companyName": "companyName",
"showLeafUserName": "boolean",
"disconnectEnabled": "boolean"
},
"provider": "providerName"
},
....
]

Get an authentication Magic Link

 GET /magic-link/authentication/{magicLinkId}

Get a created link for authentication with a single provider.

Request examples
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/authentication/{magicLinkId}'
Response
{
"id": "magicLinkId",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"createdAt": "2023-11-02T19:17:16.494Z",
"expiresAt": "2024-10-26T14:23:56.584Z",
"lastAccessedAt": "2023-11-02T19:17:18.906Z",
"leafUserId": "UUID",
"maxUsage": 3,
"usageCount": 0,
"widget": "AUTHENTICATION",
"settings": {
"backgroundColor": "codeColor",
"headerImage": "URL",
"companyLogo": "URL",
"companyName": "companyName",
"showLeafUserName": "boolean",
"disconnectEnabled": "boolean"
},
"provider": "providerName"
}

Create an authentication Magic Link

 POST /magic-link/users/{leafUserId}/authentication

Provider application info

Make sure you set up your provider application first. More info here.

Creates a link for authentication with a single provider.

  • provider: the provider to be used in the authentication process. It can be: JohnDeere, ClimateFieldView, CNHI, AgLeader, Trimble, RavenSlingshot, or Stara.
  • expiresIn: an integer number for the expiration time, in seconds. This parameter is optional and the default value is 900 (minimum) and the maximum is the equivalent to 1 year.
Request body
{
"expiresIn": int,
"provider": "providerName"
}
Request examples
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "expiresIn": int, "provider": "providerName", "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/authentication'
Response
{
"id": "magicLinkId",
"leafUserId": "UUID",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"expiresAt": "2010-10-10T10:10:10.000000000Z"
}

Delete an authentication Magic Link

 DELETE /magic-link/authentication/{magicLinkId}

Delete a link for authentication with a single provider.

Request examples
curl -X DELETE \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/authentication/{magicLinkId}'

File upload

This is a link to upload machine files.

Endpoints

DescriptionEndpoints
Get all file upload Magic LinksGET /magic-link/file-upload
Get a file upload Magic LinkGET /magic-link/file-upload/{magicLinkId}
Create a file upload Magic LinkPOST /magic-link/users/{leafUserId}/file-upload
Delete a file upload Magic LinkDELETE /magic-link/file-upload/{magicLinkId}

Get all file upload Magic Links

 GET /magic-link/file-upload

Get all file upload created links.

Request examples
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/file-upload'
Response
[
{
"id": "magicLinkId",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"createdAt": "2023-10-30T20:47:22.630Z",
"expiresAt": "2023-10-30T21:02:22.729Z",
"lastAccessedAt": "2023-10-30T20:47:28.209Z",
"leafUserId": "UUID",
"maxUsage": 3,
"usageCount": 0,
"widget": "FILEUPLOAD",
"settings": {
"backgroundColor": "codeColor",
"headerImage": "URL",
"companyLogo": "URL",
"companyName": "companyName",
"showLeafUserName": "boolean",
"disconnectEnabled": "boolean"
}
},
....
]

Get a file upload Magic Link

 GET /magic-link/file-upload/{magicLinkId}

Get a file upload created link.

Request examples
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/file-upload/{magicLinkId}'
Response
{
"id": "magicLinkId",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"createdAt": "2023-10-30T20:47:22.630Z",
"expiresAt": "2023-10-30T21:02:22.729Z",
"lastAccessedAt": "2023-10-30T20:47:28.209Z",
"leafUserId": "UUID",
"maxUsage": 3,
"usageCount": 0,
"widget": "FILEUPLOAD",
"settings": {
"backgroundColor": "codeColor",
"headerImage": "URL",
"companyLogo": "URL",
"companyName": "companyName",
"showLeafUserName": "boolean",
"disconnectEnabled": "boolean"
}
}

Create a file upload Magic Link

 POST /magic-link/users/{leafUserId}/file-upload

Creates a file upload link.

  • expiresIn: an integer number for the expiration time, in seconds. This parameter is optional and the default value is 900 (minimum) and the maximum is the equivalent to 1 year.
Request body
{
"expiresIn": int
}
Request examples
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "expiresIn": int, "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/file-upload'
Response
{
"id": "magicLinkId",
"leafUserId": "UUID",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"expiresAt": "2010-10-10T10:10:10.000000000Z"
}

Delete a file upload Magic Link

 DELETE /magic-link/file-upload/{magicLinkId}

Delete a file upload link.

Request examples
curl -X DELETE \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/widgets/api/magic-link/file-upload/{magicLinkId}'

Magic Link with Leaf User Creation

This option enables the creation of Leaf users automatically during the Magic Link creation process. The uniqueness of leaf users can be achieved using a mandatory external identifier, the externalId, which can be an ID already used in your application.

Endpoints

DescriptionEndpoints
Create a Provider Magic LinkPOST /magic-link/provider
Create an Authentication Magic LinkPOST /magic-link/authentication
Create a File Upload Magic LinkPOST /magic-link/file-upload

Create a Provider Magic Link

 POST /magic-link/provider

Provider application info

Make sure you set up your provider application first. More info here.

Creates a link for authentication across multiple providers. The leaf user will be created during this process based on the externalId.

  • provider: the provider to be used in the authentication process. It can be: JohnDeere, ClimateFieldView, CNHI, AgLeader, Trimble, RavenSlingshot, or Stara.
  • expiresIn: an integer number for the expiration time, in seconds. This parameter is optional and the default value is 900 (minimum) and the maximum is the equivalent to 1 year.
  • externalId: the client side user unique ID
  • name: it will be the name of the leaf user that we will be created. Updates in this property must be done in the Leaf user endpoints.
  • email: it will be the email of the leaf user that we will be created. Updates in this property must be done in the Leaf user endpoints.
info

The name and email parameters are optional, they will fill in the leaf user information that we will create, when they are not informed, we will fill in the name and email with the externalId information.

Request body
{
"name": "user_name",
"email": "user_email",
"externalId": "external_id",
"expiresIn": 900,
"allowedProviders": [
"provider_name"
]
}
Request examples
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "name": "user_name", "email": "user_email", "externalId": "external_id", "expiresIn": int, "allowedProviders": ["providerName"], "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/provider'
Response
{
"id": "magicLinkId",
"leafUserId": "UUID",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"expiresAt": "2010-10-10T10:10:10.000000000Z"
}

Create an Authentication Magic Link

 POST /magic-link/authentication

Provider application info

Make sure you set up your provider application first. More info here.

Creates a link for authentication with a single provider. The leaf user will be created during this process based on the externalId.

  • provider: the provider to be used in the authentication process. It can be: JohnDeere, ClimateFieldView, CNHI, AgLeader, Trimble, RavenSlingshot, or Stara.
  • expiresIn: an integer number for the expiration time, in seconds. This parameter is optional and the default value is 900 (minimum) and the maximum is the equivalent to 1 year.
  • externalId: the client side user unique ID
  • name: it will be the name of the leaf user that we will be created. Updates in this property must be done in the Leaf user endpoints.
  • email: it will be the email of the leaf user that we will be created. Updates in this property must be done in the Leaf user endpoints.
info

The name and email parameters are optional, they will fill in the leaf user information that we will create, when they are not informed, we will fill in the name and email with the externalId information.

Request body
{
"name": "user_name",
"email": "user_email",
"externalId": "external_id",
"expiresIn": 900,
"provider": "provider_name"
}
Request examples
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "name": "user_name", "email": "user_email", "externalId": "external_id", "expiresIn": int, "provider": "provider_name", "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/authentication'
Response
{
"id": "magicLinkId",
"leafUserId": "UUID",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"expiresAt": "2010-10-10T10:10:10.000000000Z"
}

Create a File Upload Magic Link

 POST /magic-link/file-upload

Create a file upload link. The leaf user will be created during this process based on the externalId.

  • expiresIn: an integer number for the expiration time, in seconds. This parameter is optional and the default value is 900 (minimum) and the maximum is the equivalent to 1 year.
  • externalId: the client side user unique ID
  • name: it will be the name of the leaf user that we will be created. Updates in this property must be done in the Leaf user endpoints.
  • email: it will be the email of the leaf user that we will be created. Updates in this property must be done in the Leaf user endpoints.
info

The name and email parameters are optional, they will fill in the leaf user information that we will create, when they are not informed, we will fill in the name and email with the externalId information.

Request body
{
"name": "user_name",
"email": "user_email",
"externalId": "external_id",
"expiresIn": 900
}
Request examples
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "name": "user_name", "email": "user_email", "externalId": "external_id", "expiresIn": int, "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/file-upload'
Response
{
"id": "magicLinkId",
"leafUserId": "UUID",
"link": "https://magic-link.withleaf.io/{magicLinkId}",
"expiresAt": "2010-10-10T10:10:10.000000000Z"
}

Link customization

The links can be customized using some properties described below. Simply fill in the settings property when creating the link.

Customization

PropertyTypeDescription
1backgroundColorstringThe application's background color in hexadecimal format, for example: "#c0392b" or "#27ae60". The default is #F5F5F5.
2companyLogostringURL for the company logo.
3companyNamestringThe company name.
4headerImagestringURL to an image that will be used as a header in the application.
5showLeafUserNamebooleanIndicates whether the Leaf user name will be displayed or not. It can be true or false. The default is false.
6disconnectedEnabledbooleanOnly enabled for provider and authentication Magic Link. Enables the option for the user to choose to disconnect from the provider at the end of the authentication process. It can be true or false. The default is false.

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "expiresIn": int, "allowedProviders": ["Other"], "settings": { "backgroundColor": "codeColor", "headerImage": "URL", "companyLogo": "URL", "companyName": "companyName", "showLeafUserName": "boolean", "disconnectEnabled": "boolean" } }'
'https://api.withleaf.io/services/widgets/api/magic-link/users/{leafUserId}/provider'
Edit this page