Skip to main content
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:
  1. Navigate to Settings > Security > API Keys
  2. Click Create API Key
  3. Enter a descriptive name (e.g., “Production CRM Integration”)
  4. Configure permissions (see below)
  5. Optionally set an expiration date
  6. 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.

​
API Key Format

ShingleAI API keys follow this format: 
sk_live_abc123...
  • sk_ - Indicates a secret key
  • live_ - 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:
ComponentDescriptionExample
ResourceWhat the key can accesscontacts, messages
ActionWhat operations are allowedread, 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.emails
  • contacts.phones
  • contacts.addresses
  • contacts.tags
  • contacts.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 CaseRecommended Expiration
Temporary integrations7-30 days
Contractor accessProject duration
Production integrations90-365 days
Internal toolsNo 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:
MetricDescription
Last UsedTimestamp of the most recent API call
CreatedWhen the key was created
ExpiresExpiration date (if set)
StatusActive, Expired, or Revoked
Use the “Last Used” timestamp to identify unused keys that should be revoked.

​
Revoking Keys

To revoke an API key:
  1. Navigate to Settings > Security > API Keys
  2. Find the key to revoke
  3. Click Revoke
  4. 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 control
  • Use environment variables or secret management services
  • Restrict file permissions on configuration files containing keys
export SHINGLEAI_API_KEY="sk_live_abc123..."

​
Key Rotation

Regularly rotate API keys to limit exposure from potential leaks:
  1. Create a new key with the same permissions
  2. Update your application to use the new key
  3. Verify the new key works in production
  4. Revoke the old key
Recommended rotation schedule:
EnvironmentRotation Frequency
ProductionEvery 90 days
DevelopmentEvery 30 days
After incidentsImmediately

​
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

ErrorCauseSolution
401 UnauthorizedInvalid or expired keyCheck key value and expiration
403 ForbiddenInsufficient permissionsVerify key has required resource/action
429 Too Many RequestsRate limit exceededImplement backoff and retry logic

​
Debugging Permission Issues

If your API key returns 403 Forbidden:
  1. Check the error response for the required permission
  2. Compare against your key’s configured permissions
  3. Update the key or create a new one with correct permissions

​
Next Steps

API Introduction

Learn how to use the ShingleAI API

Authentication

Understand API authentication methods