API Keys for Mobile Apps

API keys allow you to share your festival data with mobile apps, websites, and other services. This guide explains how to generate, manage, and use API keys safely.

What Are API Keys?

API keys are secure tokens that allow external applications to access your festival data. Think of them like special passwords that:

• Give read-only access to your active event’s data
• Work with mobile apps and websites
• Can be revoked anytime if compromised
• Are tracked so you know when they’re used

What Data Is Accessible?

API keys provide access to your active event’s public information:

• Event details (name, dates, timezone)
• Artists (names, bios, images, social links)
• Stages (names, descriptions)
• Program schedule (all performances)

What Data Is NOT Accessible?

API keys do not provide access to:

• User information or login credentials
• Billing or subscription details
• Inactive or past events
• Future events that aren’t active
• Admin settings or configuration

Who Needs API Keys?

You might need API keys if you’re working with:

• Mobile app developers building a festival app
• Website developers integrating festival schedules
• Digital signage displaying festival programs
• Third-party services that need festival data

Generating an API Key

Managing Your API Keys

Viewing API Keys

The API Keys page shows all your generated keys:

• Key name - What you named it
• Partial key - Last few characters for identification
• Created date - When the key was generated
• Created by - Which admin generated it
• Last used - When the key was last accessed (helps identify unused keys)
• Status - Active or Revoked

Revoking an API Key

If a key is compromised or no longer needed:

Deleting an API Key

To permanently remove a key from your list:

1. Click the Delete button next to a key
2. Confirm deletion
3. The key is removed from your list

Using API Keys

For App Developers

If you’re developing an app that uses Stagecraft data, here’s what developers need to know:

Endpoint Base URL:

https://your-festival-planner-domain.com/api/v1

Authentication:

• Include the API key in the X-API-Key header with each request
• Example: X-API-Key: fk_live_abc123def456...

Available Endpoints:

• GET /api/v1/event - Get active event details
• GET /api/v1/artists - Get all artists in the active event
• GET /api/v1/stages - Get all stages
• GET /api/v1/program - Get the complete program schedule

Example API Call

Here’s a simple example for developers:

curl -H "X-API-Key: fk_live_abc123..." \
  https://yourdomain.com/api/v1/artists

Rate Limits

API keys are rate-limited to prevent abuse:

• 60 requests per minute per API key
• Exceeding the limit returns a 429 error
• Limits reset every minute

Security Best Practices

Treat Keys Like Passwords

• ✅ Store keys securely (password managers, environment variables)
• ✅ Never commit keys to public code repositories
• ✅ Use environment variables in your applications
• ❌ Don’t share keys in screenshots or documentation
• ❌ Don’t email keys without encryption

Use Multiple Keys

Create separate keys for different purposes:

• One key for iOS app
• One key for Android app
• One key for website
• One key for testing/development

Why? If one key is compromised, you can revoke just that key without affecting other services.

Rotate Keys Regularly

Consider rotating (replacing) keys periodically:

1. Generate a new key
2. Update your apps to use the new key
3. Revoke the old key
4. Delete the old key after confirming everything works

Monitor Key Usage

Check the “Last Used” timestamp regularly:

• Identify keys that aren’t being used (candidates for deletion)
• Spot unusual access patterns
• Verify keys are working as expected

Revoke Immediately if Compromised

If you suspect a key has been exposed:

1. Revoke it immediately
2. Generate a new key
3. Update any apps or services using the old key

API Documentation for Developers

Response Format

All API endpoints return JSON in this format:

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Rate Limit Headers

Responses include rate limit information:

• X-RateLimit-Limit: 60 (max requests per minute)
• X-RateLimit-Remaining: Number of requests remaining
• X-RateLimit-Reset: When the limit resets

Error Responses

When something goes wrong:

{
  "success": false,
  "error": "Error message here",
  "meta": {
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Common Error Codes:

• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Key has been revoked
• 404 Not Found - Endpoint doesn’t exist
• 429 Too Many Requests - Rate limit exceeded

Common Use Cases

Mobile Festival App

Scenario: You’re building an iOS or Android app for festival attendees.

Steps:

1. Generate an API key named “Mobile App”
2. Give the key to your app developer
3. Developer integrates the API to fetch:
   • Festival lineup (artists)
   • Stage locations (stages)
   • Performance schedule (program)
4. App caches data locally and refreshes periodically

Festival Website Integration

Scenario: You want to display your program on your festival’s website.

Steps:

1. Generate an API key named “Festival Website”
2. Add key to your website’s backend code
3. Fetch program data from the API
4. Display schedule on your site
5. Update automatically when you change the program

Digital Signage

Scenario: You have digital screens showing the schedule at the festival.

Steps:

1. Generate API key named “Digital Signage”
2. Configure signage system with the key
3. System fetches current day’s schedule
4. Updates automatically every few minutes
5. Shows real-time schedule to attendees

Common Questions

Do I need an API key for normal use?

No. API keys are only needed for external integrations (mobile apps, websites, etc.). The standard Stagecraft interface doesn’t require an API key.

Can I use the same key for multiple apps?

You can, but it’s better to use separate keys for different apps. This makes it easier to track usage and revoke specific apps if needed.

How many keys can I create?

There’s no strict limit, but create only as many as you need. Each key should serve a specific purpose.

Can API keys access past events?

No. API keys only provide access to the currently active event. If you switch which event is active, the API will return data for the new active event.

What happens if I revoke a key?

The key stops working immediately. Any app or service using that key will receive authentication errors and cannot access your festival data.

Can viewers or editors generate API keys?

No. Only Admins can generate, revoke, and delete API keys.

Are API keys free?

Yes. API keys are included with your Stagecraft subscription at no additional cost.

Can I customize what data an API key can access?

Not currently. All API keys provide the same level of read-only access to the active event’s public data.

Troubleshooting

Key not working in app

If an API key isn’t working:

• Verify the key hasn’t been revoked (check API Keys page)
• Confirm the key is being sent in the X-API-Key header
• Check for typos in the key
• Verify your subscription is active
• Check that you have an active event

Rate limit errors

If you’re hitting rate limits:

• Apps should cache data locally
• Reduce the frequency of API calls
• Only fetch updates when needed (not every second)
• Consider having your app check for updates every 5-15 minutes instead

No data returned

If the API returns empty data:

• Check that you have an active event
• Verify artists/stages/performances exist in the active event
• Make sure the event isn’t empty
• Check the specific endpoint you’re using

Wrong event data

If the API shows data from the wrong event:

• Verify which event is marked as active
• Check the active event in Stagecraft
• Remember: API always returns the active event’s data

What’s Next?

Now that you understand API keys:

• Build your program → so there’s data to share
• Manage your subscription →
• Invite team members →

For technical support or API questions, contact your development team or Stagecraft support.