Authentication for Connected Accounts

When integrating with the Graniot API, you'll create connected accounts for your customers. This guide explains the two authentication methods available for performing actions on behalf of these accounts.

Understanding Connected Accounts

When you create a connected account via POST /api/accounts/, the response includes:

{
  "id": "acc-52a220de-73e9-11ee-8cc3-0242ac130002",
  "account_email": "[email protected]",
  "embedded_url": "https://embed.graniot.com/?auth_id=eyJ...",
  "account_access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

The account_access token and your API key can both be used to authenticate, but they serve different purposes.

Option 1: API Key + Account Header (Backend)

Best for: Server-side integrations, backend services, automated processes

This method uses your organization's API key with an additional header specifying which account to act on behalf of.

Headers

x-api-key: YOUR_API_KEY
Graniot-Account: acc-52a220de-73e9-11ee-8cc3-0242ac130002

Characteristics

• Non-expiring - The API key does not expire

• Full permissions - Has the same permissions as your organization

• Server-side only - Must never be exposed in client-side code

Example: Create a Farm for a Connected Account

curl

curl https://app.graniot.com/api/farms/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Graniot-Account: acc-52a220de-73e9-11ee-8cc3-0242ac130002' \
  -d '{"farm": {"name": "Customer Farm"}, "parcels": []}'

Python

Option 2: JWT Bearer Token (Frontend/Embedded)

Best for: Embedded maps, client-side applications, frontend integrations

This method uses the account_access JWT token, which is scoped to a specific connected account.

Headers

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Characteristics

• Expires in 3 hours - Must be refreshed periodically

• Scoped permissions - Limited to the specific account's data

• Safe for client-side - Can be used in frontend code (but still handle with care)

Example: Fetch Parcels for a Connected Account

curl

curl https://app.graniot.com/api/parcels/ \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...'

JavaScript

Refreshing the Token

When the JWT token expires, you need to fetch a new one from your backend:

# Backend: Fetch new token
def get_fresh_account_token(account_id):
    response = requests.get(
        f'{GRANIOT_API_ENDPOINT}accounts/{account_id}/',
        headers={'x-api-key': 'YOUR_API_KEY'}
    )
    account = response.json()
    return account['account_access']

Comparison

Feature	API Key + Header	JWT Bearer
Expiration	Never	3 hours
Use case	Backend	Frontend/Embedded
Security	Keep secret	Can expose to client
Refresh needed	No	Yes
Permissions	Full	Account-scoped

Security Best Practices

1. Never expose your API key in client-side code, mobile apps, or public repositories

2. Use JWT tokens for frontend applications and embedded maps

3. Implement token refresh logic to handle JWT expiration gracefully

4. Store API keys securely using environment variables or secret management systems

5. Use HTTPS for all API requests

Common Errors

"Invalid token"

This error occurs when:

• The JWT token has expired (after 3 hours)

• The token format is incorrect

• You're using account_access with x-api-key header instead of Authorization: Bearer

Solution: Ensure you're using the correct authentication method and refresh expired tokens.

"Account not found"

This error occurs when:

• The Graniot-Account header contains an invalid account ID

• The account has been deleted or deactivated

Solution: Verify the account ID and check the account status.