API Keys
Secure programmatic access to your workspace. Build custom integrations, automate workflows, and connect third-party applications via the Gravity Rail API.
What API Keys Do
API Keys enable programmatic access:
- Authenticate requests to the Gravity Rail API
- Scoped permissions control what each key can access
- Key management with rotation and revocation
- Usage tracking to monitor activity
- Expiration support for time-limited access
Key Features
Scoped Permissions
Grant only the permissions needed. Follow the principle of least privilege.
Key Expiration
Set expiration dates—30 days for testing, 90 days for temporary access, or no expiration for permanent integrations.
Usage Tracking
Monitor when each key was last used to identify unused keys for cleanup.
Key Format
gr_4k7n9m2p8q3r5t6v8w1x
The gr_ prefix identifies Gravity Rail API keys.
Creating an API Key
- Open Settings (top-right) and select API Keys under the Developer section
- Click Create API Key
- Configure name, scopes, and expiration
- Copy immediately — the full secret is shown only once
Using an API Key
curl -X GET "https://api.gravityrail.com/api/v2/w/{workspace_id}/members" \
-H "Authorization: Bearer gr_your_api_key_here"
Available Scopes
| Scope | Permission |
|---|---|
read:members | View member information |
write:members | Create and update members |
read:chats | Access chat history |
write:chats | Send messages |
read:data | Access data records |
write:data | Create/update data |
admin:workspace | Full workspace admin |
Security Best Practices
- Never commit keys to source control
- Store in environment variables or secret managers
- Rotate every 90 days or after team changes
- Delete unused keys promptly
- Revoke immediately if compromised
Common Use Cases
| Use Case | Scopes Needed |
|---|---|
| Automated Reports | read:members, read:data |
| CRM Sync | read:members, write:members |
| Custom Dashboard | read:chats, read:members |
| Workflow Automation | write:chats, write:workflows |
Pricing & Limits
Feature availability and limits are determined by your subscription plan. See the pricing page for details.
Related Resources
- Webhooks - Receive real-time notifications
- Integrations - Pre-built connections
- Workflows - Automate processes