API Keys
API keys are the primary method for authenticating with the HEIR API.
Overview
Each API key is tied to a specific tier that determines your rate limits and available features. Keys are associated with your user account and can be managed via the API or Dashboard.
Key Tiers
| Tier | Prefix | Rate Limit | Features |
|---|---|---|---|
| Public | heir_pk_ | 100 req/15min | Basic contract generation |
| Partner | heir_pt_ | 1,000 req/15min | + Embedding, webhooks |
| Internal | heir_in_ | 10,000 req/15min | + Admin features |
Creating API Keys
Via API
bash
curl -X POST https://api.heir.es/api/v1/api-keys \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Key",
"tier": "partner",
"scopes": ["contracts", "webhooks"]
}'Via Dashboard
- Navigate to Developer Portal
- Click "Create API Key"
- Select your desired tier and scopes
- Copy and securely store the generated key
Important
The full API key is only shown once when created. Store it securely!
Scopes
Scopes limit what an API key can do:
| Scope | Description |
|---|---|
contracts | Generate and manage contracts |
vaults | Access vault information |
webhooks | Manage webhook subscriptions |
embed | Use the embeddable wizard |
admin | Administrative operations |
Security Best Practices
- Never expose keys in client-side code
- Use environment variables for key storage
- Rotate keys regularly (quarterly recommended)
- Use IP whitelisting for production keys
- Limit scopes to only what's needed
- Monitor usage for anomalies
IP Whitelisting
Restrict API key usage to specific IP addresses:
bash
curl -X PUT https://api.heir.es/api/v1/api-keys/KEY_ID \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ip_whitelist": ["203.0.113.10", "203.0.113.11"]
}'Key Rotation
- Create a new key with the same permissions
- Update your application to use the new key
- Verify the new key works correctly
- Revoke the old key