User Roles and Permissions

Connected accounts can have different roles that control what they can do in the embedded map. This guide explains the available roles and how to manage them.

Available Roles

Role	Description
USER	View-only access. Cannot edit parcel geometries or manage resources.
TECHNICIAN	Can view and edit parcel geometries in the embedded map.
COMPANY_ADMIN	Full access to view, edit, and manage all resources.

Permissions by Role

Action	USER	TECHNICIAN	COMPANY_ADMIN
View parcels	Yes	Yes	Yes
View satellite imagery	Yes	Yes	Yes
Edit parcel geometries	No	Yes	Yes
Delete parcels	No	No	Yes
Manage account settings	No	No	Yes

Use Case: Preventing Geometry Edits

A common requirement is to prevent end users from editing parcel geometries in the embedded map - especially when you want to maintain control over the data from your backend system.

Solution: Assign the USER role to accounts that should only view data.

When an account has the USER role:

• The edit and delete buttons are not shown in the embedded map

• Users can view all parcels and satellite imagery

• Any geometry changes must be done through your backend via the API

Checking an Account's Role

Retrieve account details to see the current role:

curl

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

Python

Changing Account Roles

Use the set_role endpoint to change an account's role:

POST /api/accounts/{account_id}/set_role/

curl

# Set to USER (view-only)
curl https://app.graniot.com/api/accounts/acc-52a220de-73e9-11ee-8cc3-0242ac130002/set_role/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"role": "USER"}'

# Set to TECHNICIAN (can edit)
curl https://app.graniot.com/api/accounts/acc-52a220de-73e9-11ee-8cc3-0242ac130002/set_role/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"role": "TECHNICIAN"}'

Python

License Requirements

Changing roles may require available licenses:

• Upgrading from USER to TECHNICIAN requires an available technician license

• The system will check license availability before making the change

• If no licenses are available, the request will fail with an error

If you receive a license error when changing roles, contact Graniot support to review your license allocation.

Default Role for New Accounts

When you create a new connected account via the API, the default role depends on your organization's settings. If you need accounts to start with a specific role, call set_role immediately after creation:

# Create account
response = requests.post(f'{GRANIOT_API_ENDPOINT}accounts/', headers=HEADERS, json={'account_email': '[email protected]'})
account = response.json()

# Immediately set to USER role (view-only)
requests.post(
    f'{GRANIOT_API_ENDPOINT}accounts/{account["id"]}/set_role/',
    headers=HEADERS,
    json={'role': 'USER'}
)

Integration Pattern: Read-Only Embedded Maps

For integrations where users should only view data (no editing):

1. Create connected accounts via API

2. Set each account to USER role

3. Provide the embedded URL to your frontend

4. Handle all data modifications through your backend using the API

def create_readonly_account(email):
    """Create a connected account with view-only access."""

    # Create the account
    response = requests.post(
        f'{GRANIOT_API_ENDPOINT}accounts/',
        headers=HEADERS,
        json={'account_email': email}
    )
    account = response.json()

    # Set to USER role (view-only)
    requests.post(
        f'{GRANIOT_API_ENDPOINT}accounts/{account["id"]}/set_role/',
        headers=HEADERS,
        json={'role': 'USER'}
    )

    return account

Troubleshooting

"License not available" error

This occurs when trying to upgrade to a role that requires more licenses than you have available.

Solution: Contact Graniot support to purchase additional licenses or downgrade other accounts.

Role change not taking effect

If a user still sees edit controls after changing their role:

1. Have the user refresh their browser

2. Clear browser cache

3. Verify the embedded URL token has been refreshed (tokens cache role information)

Cannot change role

If you cannot change an account's role:

1. Verify you're using the correct API key with appropriate permissions

2. Check that the account ID is correct

3. Ensure the account is active (not deactivated)