API Authentication
Learn how to generate, manage, and use API keys to authenticate requests to the ExperienceLocal API. Secure your integrations with scoped permissions and rate limiting.
Authentication Methods
ExperienceLocal uses API keys to authenticate requests. API keys are scoped to your organization and can be configured with specific permissions to limit access to only what your integration needs.
API Keys
The primary authentication method for all API requests. Keys are SHA-256 hashed and support fine-grained permission scopes.
- Organization-scoped access
- Configurable permissions
- Per-key rate limits
- IP and domain restrictions
Security Features
Enterprise-grade security built into every API key to protect your data and prevent unauthorized access.
- SHA-256 hashing (never stored plaintext)
- Checksum validation
- Expiration dates
- Full audit logging
Plan Requirements
API key creation is available on the Growth plan and above. Different plans have limits on the number of active keys you can create:
- • Growth: 5 active keys
- • Scale: 20 active keys
- • Enterprise: 100 active keys
Generating API Keys
Create API keys from your dashboard with custom names, descriptions, and permission scopes.
Step-by-Step Guide
- 1Navigate to API Keys
Go to Dashboard → Settings → API Keys
- 2Click "Create API Key"
You'll be prompted to configure the key settings
- 3Configure Key Settings
- • Name: A descriptive name (e.g., "Production Widget")
- • Environment: Live or Test
- • Permissions: Choose a preset or customize scopes
- • Restrictions: Optional IP/domain allowlists
- 4Save Your Key Securely
The full key is shown only once. Copy it immediately and store it in a secure location.
API Key Format
live or testSave Your Key Immediately
After creating an API key, the full key value is displayed only once and cannot be retrieved again. If you lose a key, you'll need to generate a new one. Store keys in a secure password manager or environment variables - never commit them to version control.
Using API Keys
Include your API key in the Authorization header of every request using the Bearer token format.
# Using curl
curl https://api.experiencelocal.io/v1/experiences \
-H "Authorization: Bearer el_live_k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6_x7y8"
# Using fetch in JavaScript
const response = await fetch('https://api.experiencelocal.io/v1/experiences', {
headers: {
'Authorization': 'Bearer el_live_k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6_x7y8',
'Content-Type': 'application/json',
},
});
# Using Node.js with axios
const axios = require('axios');
const response = await axios.get('https://api.experiencelocal.io/v1/experiences', {
headers: {
'Authorization': 'Bearer el_live_k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6_x7y8',
},
});
# Using Python with requests
import requests
headers = {
'Authorization': 'Bearer el_live_k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6_x7y8',
}
response = requests.get('https://api.experiencelocal.io/v1/experiences', headers=headers)- • Use
Authorizationheader - • Include
Bearerprefix - • Use full key including checksum
- • Send over HTTPS only
- • Don't use query parameters
- • Don't omit
Bearerprefix - • Don't expose keys in client-side code
- • Don't send keys over HTTP
Environment Variables
Store API keys in environment variables, not in your code:
Then reference them in your application: process.env.EXPERIENCELOCAL_API_KEY
Key Permissions
Control what each API key can access using fine-grained permission scopes. Choose from preset permission levels or customize individual scopes.
Read-Only Access
Safe for client-side use. Can view data but cannot make changes.
Widget Access
Read access plus ability to create bookings. For embedded booking widgets.
Full Access
Complete control including analytics and availability management.
Available Scopes
experiences:readView experience details, photos, pricing, and descriptions
bookings:readView booking details and status
availability:readCheck available time slots and capacity
properties:readView property information and settings
analytics:readAccess booking analytics and revenue reports
bookings:writeCreate and modify bookings
availability:writeUpdate availability and capacity
widget:accessAccess widget-specific endpoints
Principle of Least Privilege
Only grant the minimum permissions needed for your use case. For example, if you're building a read-only analytics dashboard, use the readonly preset rather than full access. This limits potential damage if a key is compromised.
Security Best Practices
Follow these guidelines to keep your API keys secure and prevent unauthorized access.
Never Expose Keys
- Don't commit keys to version control (Git)
- Don't include keys in client-side JavaScript
- Don't share keys in public forums or chat
- Don't log keys in application logs
Store Securely
- Use environment variables or secret managers
- Encrypt keys at rest in your infrastructure
- Use separate keys for different environments
- Restrict access to keys within your team
Restrict Access
- Set IP allowlists for server-to-server keys
- Configure domain restrictions for widget keys
- Use minimal permission scopes
- Set expiration dates for temporary access
Monitor Usage
- Regularly review API key usage logs
- Monitor for unusual request patterns
- Check for unexpected IP addresses
- Revoke inactive or suspicious keys immediately
If a Key is Compromised
If you suspect an API key has been exposed or compromised:
- 1. Revoke the key immediately from the dashboard
- 2. Generate a new key with fresh credentials
- 3. Update your application to use the new key
- 4. Review usage logs for any unauthorized activity
- 5. Contact support if you notice suspicious usage
Rotating Keys
Regularly rotate your API keys as a security best practice. Key rotation creates a new key while marking the old one as rotated.
Rotation Process
- 1Initiate Rotation
Click "Rotate" on the key you want to replace in the dashboard
- 2New Key Generated
System creates a new key with identical permissions and settings
- 3Update Your Application
Replace the old key with the new key in your environment variables or secrets manager
- 4Old Key Revoked
The old key is automatically marked as "rotated" and can no longer be used
When to Rotate
- • Every 90 days as a routine practice
- • When an employee with access leaves
- • After suspected security incident
- • When changing hosting providers
Benefits of Rotation
- • Limits exposure window of compromised keys
- • Meets compliance requirements
- • Provides audit trail of key changes
- • No downtime with proper planning
Zero-Downtime Rotation
For critical production systems, create a new key first, deploy your application with the new key, verify it's working, then revoke the old key. This ensures continuous service during the rotation process.
Rate Limits
API keys are subject to rate limits to ensure fair usage and system stability. Limits vary by endpoint type and your subscription plan.
| Endpoint Type | Per Minute | Per Day |
|---|---|---|
| Widget API | 100 requests | Unlimited |
| Booking API | 30 requests | 100 requests |
| Validation API | 60 requests | Unlimited |
Rate Limit Headers
Every API response includes rate limit information in the headers:
Handling Rate Limits
If you exceed rate limits, you'll receive a 429 response:
- Check
Retry-Afterheader - Implement exponential backoff
- Cache responses where appropriate
Custom Rate Limits
Need higher rate limits? Enterprise plans can configure custom per-key rate limits. Contact our sales team to discuss your requirements.
Troubleshooting
Common API authentication issues and how to resolve them.
401 Unauthorized
Your API key is invalid, revoked, or missing.
- • Verify the key includes the
Bearerprefix - • Check that the key hasn't been revoked in the dashboard
- • Ensure you're copying the entire key including checksum
- • Verify the environment (test vs live) matches
403 Forbidden
Your API key doesn't have permission for this operation.
- • Check the key's permission scopes in the dashboard
- • Verify you're using the correct permission preset
- • Ensure the endpoint requires permissions you have
- • Create a new key with appropriate scopes if needed
429 Too Many Requests
You've exceeded the rate limit for this key.
- • Wait for the time specified in
Retry-Afterheader - • Implement request throttling in your application
- • Add caching to reduce duplicate requests
- • Contact support for custom rate limits
Key Not Working After Creation
Newly created key returns authentication errors.
- • Allow up to 60 seconds for key propagation
- • Verify you copied the entire key when it was displayed
- • Check that the key status shows "Active" in dashboard
- • Ensure no IP or domain restrictions are blocking you
Related Documentation
Learn more about the ExperienceLocal API and integration options.
API Reference
Complete endpoint documentation with request/response examples.
Webhooks
Receive real-time notifications about bookings and events.
Widget Embedding
Add the booking widget to your website with API keys.
Error Handling
Understand error codes and how to handle API failures.
Need Help with API Integration?
Our developer support team can help with authentication issues, integration questions, and custom requirements.
Contact Developer Support