Account Lifecycle

This guide explains how to manage the complete lifecycle of connected accounts, including creation, deactivation, and permanent deletion.

Creating Accounts

Create a connected account for each of your customers:

curl

curl https://app.graniot.com/api/accounts/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"account_email": "[email protected]"}'

Python

The account_email is used as an identifier only - no email is sent to this address.

Account States

Accounts can be in one of these states:

State	Description	API Access	Visible in UI
Active	Normal operation	Yes	Yes
Deactivated	Soft-deleted via API	No	Yes (in Members)
Deleted	Permanently removed	No	No

Soft Delete vs Permanent Delete

Soft Delete (API)

The DELETE /api/accounts/{id}/ endpoint performs a soft delete:

curl https://app.graniot.com/api/accounts/acc-52a220de-73e9-11ee-8cc3-0242ac130002/ \
  -X DELETE \
  -H 'x-api-key: YOUR_API_KEY'

What happens:

• The account is deactivated (not removed)

• All associated data (farms, parcels) is preserved

• The account email cannot be reused for a new account

• The account can be reactivated

Common Issue: If you soft-delete an account and try to create a new account with the same email, you'll receive an error. This is because the email is still associated with the deactivated account.

Permanent Delete (Admin Panel)

To permanently remove an account and free up the email for reuse:

1. Log in to the Graniot App

2. Go to Settings > Members

3. Find the deactivated account in the list

4. Click the permanent delete button

What happens:

• The account is completely removed from the system

• The email can be used for a new account

• All associated data is permanently deleted

Reactivating Accounts

Deactivated accounts can be reactivated from the Admin Panel:

1. Go to Settings > Members

2. Find the deactivated account

3. Click the reactivate button

The account will return to active status with all its data intact.

Avoiding Orphan Resources

When managing accounts and their resources, be careful to avoid creating "orphan" farms or parcels.

What Causes Orphans

Orphan farms are created when you:

• Unlink a farm from an account via the UI without deleting it

• Delete an account without first deleting its farms

Problems with Orphans

• Orphan farms still count toward your billing (hectares)

• They're not visible via the API or standard UI

• They can only be managed via the Data Management panel

Best Practices

1. Delete farms before accounts - Always delete farms via the API before deleting the account

2. Use API for farm management - Prefer DELETE /api/farms/{id}/ over UI unlinking

3. Monitor Data Management - Periodically check Settings > Data Management for orphan farms

Cleaning Up Orphans

If you have orphan farms:

1. Go to Settings > Data Management

2. View all farms associated with your organization

3. Identify orphan farms (those not linked to any account)

4. Delete them permanently

Complete Account Deletion Workflow

For a clean account deletion that avoids orphans:

import requests

GRANIOT_API_ENDPOINT = 'https://app.graniot.com/api/'
HEADERS = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
}

def delete_account_completely(account_id):
    # 1. Get all farms for this account
    headers_with_account = {**HEADERS, 'Graniot-Account': account_id}
    farms_response = requests.get(
        f'{GRANIOT_API_ENDPOINT}farms/',
        headers=headers_with_account
    )
    farms = farms_response.json()

    # 2. Delete each farm (this also deletes all parcels)
    for farm in farms:
        requests.delete(
            f'{GRANIOT_API_ENDPOINT}farms/{farm["id"]}/',
            headers=headers_with_account
        )

    # 3. Soft-delete the account
    requests.delete(
        f'{GRANIOT_API_ENDPOINT}accounts/{account_id}/',
        headers=HEADERS
    )

    # 4. Permanent deletion must be done via Admin Panel
    print(f"Account {account_id} soft-deleted.")
    print("For permanent deletion, go to Settings > Members in the Graniot App.")