API Keys
Generate and manage API keys to access Grillo Cloud data programmatically.
Overview
API keys allow you to:
- Access sensor data via API
- Integrate with external systems
- Build custom applications
- Automate data export
Accessing API key management
- Navigate to Settings → API Keys
- Or Profile → Developer Settings → API Keys
Creating an API key
Step 1: Start key creation
- Click "Create API Key" or "+" button
- The key creation form opens
Step 2: Configure the key
| Field | Description |
|---|---|
| Name | Descriptive name (e.g., "Production App") |
| Description | Purpose of this key |
| Permissions | What the key can access |
| Expiration | When the key expires (optional) |
Step 3: Set permissions
Choose what the key can do:
| Permission | Description |
|---|---|
| Read sensors | View sensor list and data |
| Read events | View detected events |
| Write configuration | Modify sensor settings |
| Admin | Full API access |
warning
Follow the principle of least privilege - only grant permissions actually needed.
Step 4: Generate the key
- Review settings
- Click "Create"
- Copy the key immediately - it won't be shown again
Managing API keys
Viewing keys
The API keys list shows:
- Key name
- Creation date
- Last used
- Permissions
- Status (active/revoked)
Key details
Click a key to view:
- Full configuration
- Usage statistics
- Activity log
Editing keys
You can modify:
- Name and description
- Permissions (may require regeneration)
- Expiration date
You cannot modify:
- The key value itself
- Creation date
Revoking keys
To disable a key:
- Find the key in the list
- Click "Revoke" or the menu → Revoke
- Confirm the action
Effects of revoking:
- Key immediately stops working
- API calls with this key will fail
- Cannot be undone (create a new key instead)
Deleting keys
To permanently remove a key:
- Find the key in the list
- Click "Delete" or menu → Delete
- Confirm deletion
API key security
Best practices
-
Never share keys publicly
- Don't commit to version control
- Don't share in public forums
- Use environment variables
-
Use separate keys for different purposes
- Development vs production
- Different applications
- Different team members
-
Set expiration dates
- Rotate keys regularly
- Automatically expire unused keys
-
Limit permissions
- Only grant what's needed
- Use read-only when possible
-
Monitor usage
- Review activity logs
- Watch for unusual patterns
- Set up usage alerts
Storing keys safely
Do:
- Store in environment variables
- Use secrets management systems
- Encrypt at rest
Don't:
- Hard-code in source code
- Store in plain text files
- Share via email or chat
If a key is compromised
- Revoke immediately - Disable the key
- Create new key - Generate replacement
- Update applications - Deploy new key
- Review logs - Check for unauthorized use
- Investigate - Determine how it was exposed
Rate limits
API keys have usage limits:
| Tier | Requests/minute | Requests/day |
|---|---|---|
| Free | 60 | 10,000 |
| Standard | 300 | 100,000 |
| Premium | 1,000 | Unlimited |
Handling rate limits
When limits are exceeded:
- API returns 429 status code
- Retry-After header indicates wait time
- Implement exponential backoff
Using API keys
Authentication
Include the API key in requests:
Header method (recommended):
Authorization: Bearer YOUR_API_KEY
Query parameter method:
?api_key=YOUR_API_KEY
Example request
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.grillo.io/v1/sensors
Troubleshooting
Key not working
- Verify key is not revoked
- Check key permissions
- Verify correct header format
- Check for typos
- Ensure key hasn't expired
Permission denied errors
- Check key has required permission
- Verify resource is in your organization
- Review API documentation for required permissions
Rate limit errors
- Reduce request frequency
- Implement caching
- Use batch endpoints
- Upgrade tier if needed