Skip to main content
The ShingleAI API uses API keys to authenticate requests. You can create and manage API keys from your organization settings in the dashboard.

​
Creating an API Key

  1. Sign in to the ShingleAI Dashboard
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., “Production Server” or “Development”)
  5. Select the permission scopes your key needs
  6. Click Create and copy your key immediately
Your API key is only shown once when created. Store it securely - you won’t be able to see it again. If you lose your key, you’ll need to create a new one.

​
Using Your API Key

Include your API key in the Authorization header of every request using the Bearer token format: 
Authorization: Bearer your-api-key

curl https://api.shingleai.com/v1/contacts \
  -H "Authorization: Bearer sk_live_abc123..."

​
Permission Scopes

API keys are scoped to specific permissions that control what resources they can access. When creating a key, grant only the permissions your integration needs.

​
Available Scopes

ResourceActionsDescription
contactsread, write, deleteManage contacts and their details
customersread, write, deleteManage customer records
businessesread, write, deleteManage business profiles
messagesread, write, deleteAccess email, SMS, and voice messages
automationsread, write, deleteConfigure automation workflows
domainsread, write, deleteManage custom domains
usersread, write, deleteManage user profiles and settings
organizationread, write, deleteManage organization settings and members
api_keysread, write, deleteManage API keys and their permissions
resourcesread, write, deleteAccess shared resources and analytics

​
Permission Inheritance

Permissions follow a hierarchical model. Granting access to a parent resource also grants access to its child resources:
  • contacts includes contacts.emails, contacts.phones, contacts.addresses, contacts.tags, contacts.notes
  • customers includes customers.contacts
  • businesses includes businesses.details, businesses.tags, businesses.contacts, businesses.addresses
  • messages includes messages.email, messages.sms, messages.voice
  • automations includes automations.actions
  • domains includes domains.dns, domains.verification
  • users includes users.profile, users.settings
  • organization includes organization.settings, organization.billing
  • resources includes resources.analytics

​
HTTP Methods and Permissions

HTTP MethodRequired Permission
GETread
POSTwrite
PUT, PATCHwrite
DELETEdelete

​
Authentication Errors

If authentication fails, you’ll receive a 401 Unauthorized response: 
{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid or missing API key"
    }
}
Common causes:
  • Missing Authorization header
  • Invalid or revoked API key
  • Malformed Bearer token (missing “Bearer ” prefix)
If your key lacks permission for a specific action, you’ll receive a 403 Forbidden response: 
{
    "error": {
        "code": "INSUFFICIENT_PERMISSIONS",
        "message": "Missing write permission for contacts",
        "details": {
            "required": {
                "resource": "contacts",
                "action": "write"
            },
            "hint": "Contact your administrator to request additional permissions"
        }
    }
}

​
Security Best Practices

Use environment variables or a secrets manager to store your API keys. Add .env files to your .gitignore.
# .env (never commit this file)
SHINGLEAI_API_KEY=sk_live_abc123...

// Use environment variables
const apiKey = process.env.SHINGLEAI_API_KEY;
Create different API keys for development, staging, and production. This limits the blast radius if a key is compromised.
Follow the principle of least privilege. Only grant the specific permissions your integration needs. A read-only dashboard doesn’t need write access.
Periodically create new API keys and deprecate old ones. This limits the window of exposure if a key is leaked.
Review your API key activity in the dashboard regularly. Revoke any keys showing suspicious activity immediately.

​
Server-Side Only

API keys should only be used in server-side code. Never expose your API key in client-side JavaScript, mobile apps, or any code that runs in the browser.
If you need to access the ShingleAI API from a client application, implement a backend proxy that handles authentication on behalf of your users.