API keys allow external applications and scripts to access your ShingleAI organization programmatically. This guide covers creating, configuring, and securing your API keys.
This guide covers API keys for REST API access. For MCP keys used by AI agents, see MCP Key Management . Prerequisites
You must be an Owner to manage API keys
Admins and Users cannot create, view, or revoke API keys
Creating an API Key To create a new API key:
Navigate to Settings > Security > API Keys
Click Create API Key
Enter a descriptive name (e.g., “Production CRM Integration”)
Configure permissions (see below)
Optionally set an expiration date
Click Create
The full API key is displayed only once after creation. Copy it immediately and store it securely. You cannot retrieve the full key later.
ShingleAI API keys follow this format:
sk_ - Indicates a secret keylive_ - Environment (live for production)Followed by a unique identifier
Setting Permissions API keys support fine-grained permissions that control which resources the key can access and what actions it can perform.
Permission Structure Each permission specifies:
Component Description Example Resource What the key can access contacts, messagesAction What operations are allowed read, write, delete
Common Permission Patterns Read-Only Access { "contacts" : { "read" : true , "write" : false , "delete" : false }, "customers" : { "read" : true , "write" : false , "delete" : false } } Full Contact Management { "contacts" : { "read" : true , "write" : true , "delete" : true } } Messaging Only { "messages" : { "read" : true , "write" : true , "delete" : false } } Permission Inheritance Permissions cascade to child resources. Granting access to contacts automatically includes:
contacts.emailscontacts.phonescontacts.addressescontacts.tagscontacts.notes
You can override child permissions to restrict access further.
Key Expiration Set an expiration date to automatically disable API keys after a certain period:
Use Case Recommended Expiration Temporary integrations 7-30 days Contractor access Project duration Production integrations 90-365 days Internal tools No expiration (rotate manually)
Expired keys return a 401 Unauthorized error. Create a new key before the old one expires to avoid service interruption.
Monitoring Key Usage Track API key activity from the API Keys dashboard:
Metric Description Last Used Timestamp of the most recent API call Created When the key was created Expires Expiration date (if set) Status Active, Expired, or Revoked
Use the “Last Used” timestamp to identify unused keys that should be revoked.
Revoking Keys To revoke an API key:
Navigate to Settings > Security > API Keys
Find the key to revoke
Click Revoke
Confirm the action
Revoked keys cannot be restored. Any application using the revoked key will immediately lose access.
When to Revoke Revoke API keys immediately when:
A key may have been compromised
An employee with key access leaves the organization
An integration is decommissioned
A key hasn’t been used in 90+ days
Security Best Practices Key Storage
Never commit API keys to version controlUse environment variables or secret management services
Restrict file permissions on configuration files containing keys
Environment Variable
TypeScript
Python
export SHINGLEAI_API_KEY = "sk_live_abc123..."
Key Rotation Regularly rotate API keys to limit exposure from potential leaks:
Create a new key with the same permissions
Update your application to use the new key
Verify the new key works in production
Revoke the old key
Recommended rotation schedule:
Environment Rotation Frequency Production Every 90 days Development Every 30 days After incidents Immediately
Principle of Least Privilege Grant only the permissions each integration needs:
Read-only keys for reporting and analytics
Resource-specific keys for focused integrations
Separate keys for separate applications
Audit Regularly Review your API keys monthly:
Remove unused keys (no activity in 90+ days)
Verify permissions match current requirements
Check expiration dates and rotate as needed
Troubleshooting Common Errors Error Cause Solution 401 UnauthorizedInvalid or expired key Check key value and expiration 403 ForbiddenInsufficient permissions Verify key has required resource/action 429 Too Many RequestsRate limit exceeded Implement backoff and retry logic
Debugging Permission Issues If your API key returns 403 Forbidden:
Check the error response for the required permission
Compare against your key’s configured permissions
Update the key or create a new one with correct permissions
Next Steps 
