Leaf Connect

About

The Leaf API allows an API Owner to grant permission to access Field Boundaries, Field Operations and Machine Data Files to other API Owners. The access is controlled at the Leaf user level by the API account that owns the data.

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

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

How it works

Scenario

API Owner A wants to grant permission to API Owner B to read their fields.

1 - Sharing Relation

The first step is to create a relationship between the API Owners, from who owns the data - the sender (API Owner A) to the receiver (API Owner B). Check the endpoint Create an API Owner sharing relation.

The receiver API Owner (API Owner B) must confirm the relationship changing the relation status to ALLOWED.

This relationship status can be changed in the future by both sides, but once the sender blocks the relationship, the receiver will not be able to access the data, nor to reactivate the sharing relation status.

This step is only necessary once, that is, it is not necessary to repeat this step for new integrations with the same receiver.

2 - Permissions

In this step, permissions are granted for the resources of each Leaf user. More info here.

Note: This permission is READ only and FIELDS and OPERATIONS resources are available.

Company

Company-level sharing is not supported, but the permission can be granted or revoked at the same time the Leaf user is added or removed from the company.

3 - Access

At the end of these steps, API Owner B will be able to visualize the fields, operations and/or machine data files from the shared Leaf user, using the existing field/operations/machine data files endpoints, like this one.

Endpoints

This service has the following endpoints available:

DescriptionEndpoints
Get API Owner sharing relationGET /usermanagement/api/api-owners/sharing-relation/{RelationRole}
Get API Owner sharing relation statusGET /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{targetApiOwner}/status
Create an API Owner sharing relationPOST /usermanagement/api/api-owners/sharing-relation/receiver
Update an API Owner sharing relation statusPATCH /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{targetApiOwner}
Get LeafUser permissionsGET /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{TargetApiOwner}/users-permissions/{leafUserId}
Create a LeafUser permissionsPOST /usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}
Update LeafUser permissionsPATCH /usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}/{RESOURCE}
Invalidate receiver's tokensPOST /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{TargetApiOwner}/invalidate-tokens
Delete LeafUser sharing permissionsDELETE /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{ReceiverApiOwner}/users-permissions/{leafUserId}

Get API Owner sharing relation

 GET /usermanagement/api/api-owners/sharing-relation/{RelationRole}

Get all API Owners relation based on the relation role: SENDER or RECEIVER.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver'

Response

[
{
"senderApiOwner": "{senderApiOwner}",
"receiverApiOwner": "{receiverApiOwner}",
"status": "ALLOWED"
}
]

Get API Owner sharing relation status

 GET /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{targetApiOwner}/status

Get the relation status based in the relation role (SENDER or RECEIVER).

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/status'

Response

A string with one of the following values: PENDING, ALLOWED or BLOCKED.

"PENDING"

Create an API Owner sharing relation

 POST /usermanagement/api/api-owners/sharing-relation/receiver

Create a sharing relation between the API Owners.

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "receiverApiOwner": "{ReceiverApiOwner}" }'
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver'

Response

{
"senderApiOwner": "{senderApiOwner}",
"receiverApiOwner": "{receiverApiOwner}",
"status": "PENDING"
}

Update an API Owner sharing relation status

 PATCH /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{targetApiOwner}

Update the sharing relation status. The values available are ALLOWED or BLOCKED.

After the sender creates a relationship, the recevier must approve it by changing the status from PENDING to ALLOWED. Both API Owners can block the relation, but once locked by the sender, there is no way for the receiver to change it again.

Request examples

curl -X PATCH \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "status": "ALLOWED or BLOCKED" }'
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}'

Response

{
"senderApiOwner": "{senderApiOwner}",
"receiverApiOwner": "{receiverApiOwner}",
"status": "ALLOWED"
}

Get LeafUser permissions

 GET /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{TargetApiOwner}/users-permissions/{leafUserId}

Get all permissions granted to a receiver API Owner for a Leaf user.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}'

Response

{
"permissions": {
"FIELDS": {
"actions": [
"READ"
]
}
}
}

Create a LeafUser permissions

 POST /usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}

Grants permission to a receiver for a given Leaf user resource.

Note: shared Leaf users (from other API Owner) are not available for grant permissions

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{"permissions":{"FIELDS":{"actions":["READ"]},"OPERATIONS":{"actions":["READ"],"types":["PLANTED"]}}}'
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}'

Response

{
"leafUserId": "{leafUserId}",
"permissions": {
"FIELDS": {
"actions": [
"READ"
]
},
"OPERATIONS": {
"actions": [
"READ"
],
"types": [
"PLANTED"
]
}
}
}

Availability

ResourceActionsTypes
FIELDREAD-
OPERATIONSREADAPPLIED, HARVESTED, PLANTED

Update LeafUser permissions

 PATCH /usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}/{RESOURCE}

Update the permissions granted to the receiver API Owner.

Request examples

curl -X PATCH \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{"actions":["READ"],"types":["PLANTED", "HARVESTED"]}' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}/OPERATIONS'

Response

{
"leafUserId": "{leafUserId}",
"permissions": {
"FIELDS": {
"actions": [
"READ"
]
},
"OPERATIONS": {
"actions": [
"READ"
],
"types": [
"PLANTED", "HARVESTED"
]
}
}
}

Availability

ResourceActionsTypes
FIELDREAD-
OPERATIONSREADAPPLIED, HARVESTED, PLANTED

Invalidate receiver's tokens

 POST /usermanagement/api/api-owners/sharing-relation/{RelationRole}/{TargetApiOwner}/invalidate-tokens

Invalidate the receiver's tokens created before the current date and time.

Request examples

curl -X PATCH \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/{TargetApiOwner}/invalidate-tokens'

Delete LeafUser sharing permissions

 DELETE /usermanagement/api/api-owners/sharing-relation/{RelationRole}/users-permissions/{leafUserId}

Deletes a permission.

Request examples

curl -X DELETE \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}'
Edit this page