Leaf Connect lets one API owner grant read access to their field boundaries and field operations to another API owner. Access is controlled per Leaf user, so you share exactly the data you choose.
How it works
Sharing data between two API owners involves three steps:
1. Create a sharing relation. The data owner (sender) creates a relation naming the receiver API owner. This relation starts in PENDING status.
2. Receiver accepts. The receiver changes the relation status to ALLOWED. Either side can later change it to BLOCKED. If the sender blocks the relation, the receiver cannot reactivate it.
3. Grant permissions per Leaf user. The sender grants READ access on specific resources (FIELDS, OPERATIONS) for individual Leaf users. The receiver can then query the standard field and operations endpoints to see the shared data.
Permissions are READ only. The receiver cannot modify shared data. Company-level sharing is not supported, but you can grant or revoke permissions when adding or removing a Leaf user from a company.
Endpoints
Base URL: https://api.withleaf.io/services/usermanagement/api
Sharing relations
| Action | Method | Path |
|---|
| Get relations by role | GET | /api-owners/sharing-relation/{RelationRole} |
| Get relation status | GET | /api-owners/sharing-relation/{RelationRole}/{targetApiOwner}/status |
| Create relation | POST | /api-owners/sharing-relation/receiver |
| Update relation status | PATCH | /api-owners/sharing-relation/{RelationRole}/{targetApiOwner} |
| Invalidate receiver’s tokens | POST | /api-owners/sharing-relation/{RelationRole}/{targetApiOwner}/invalidate-tokens |
RelationRole is either SENDER or RECEIVER, depending on which side is making the request.
Relation statuses: PENDING, ALLOWED, BLOCKED.
Leaf user permissions
| Action | Method | Path |
|---|
| Get permissions | GET | /api-owners/sharing-relation/{RelationRole}/{TargetApiOwner}/users-permissions/{leafUserId} |
| Create permissions | POST | /api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId} |
| Update permissions | PATCH | /api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}/{RESOURCE} |
| Delete permissions | DELETE | /api-owners/sharing-relation/{RelationRole}/{ReceiverApiOwner}/users-permissions/{leafUserId} |
Available permission resources
| Resource | Actions | Types |
|---|
FIELDS | READ | (none) |
OPERATIONS | READ | APPLIED, HARVESTED, PLANTED |
Example: granting field and operation access
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{"permissions": {"FIELDS": {"actions": ["READ"]}, "OPERATIONS": {"actions": ["READ"], "types": ["PLANTED", "HARVESTED"]}}}' \
'https://api.withleaf.io/services/usermanagement/api/api-owners/sharing-relation/receiver/{ReceiverApiOwner}/users-permissions/{leafUserId}'
{
"leafUserId": "leaf-user-id",
"permissions": {
"FIELDS": { "actions": ["READ"] },
"OPERATIONS": { "actions": ["READ"], "types": ["PLANTED", "HARVESTED"] }
}
}
What to do next
