Developer APIAPI Key Management

API Key Management

API keys are the authentication method for using the Firstage API. This guide explains how to create, manage, and delete API keys.

What is an API Key?

API keys have the following characteristics:

  • Unique string starting with the fak_ prefix
  • Shown only once during creation (cannot be viewed later)
  • Managed per workspace
  • Granular permission settings available

Creating an API Key

Step 1: Access Developer Center

  1. Log in to Firstage dashboard
  2. Click Developer menu in the left sidebar
  3. Select API Keys tab

Step 2: Create New API Key

  1. Click Create API Key button
  2. Enter required information:
    • Name: Name indicating the key’s purpose (e.g., “Production API Key”)
    • Description (optional): Detailed purpose description
    • Permissions: Select required permissions

Step 3: Select Permissions

Select the permissions the API key can access:

Available Permissions

  • contents:read - Read content
  • contents:write - Create and update content
  • schedules:read - Read schedules
  • schedules:write - Create and update schedules

Note: Currently only content and schedule permissions are supported. Additional APIs will be released gradually.

Step 4: Set Rate Limit (Optional)

Set the number of API requests allowed per hour.

  • Default: 1,000 requests/hour
  • Maximum: 10,000 requests/hour (varies by plan)

Step 5: Save API Key

  1. Click Create button
  2. The generated API key will be displayed in a popup
  3. Important: This key won’t be shown again, so copy it to a secure location
fak_Abc123XyZ789...
  1. Store it in environment variables or a secrets management tool

Viewing API Keys

View Key List

You can view all created keys on the API Keys page in the Developer Center.

Information displayed:

  • Name: API key name
  • Key Prefix: First 10 characters of the key (e.g., fak_Abc123)
  • Permissions: List of configured permissions
  • Rate Limit: Allowed requests per hour
  • Status: active, revoked, expired
  • Last Used: Time of last API call
  • Created: Key creation date

Identifying by Key Prefix

You can’t view the full key, but you can identify which key it is by the key prefix (fak_Abc123).

Deleting API Keys

API keys should be deleted immediately if they’re no longer needed or have been exposed.

How to Delete

  1. Find the key to delete in the API key list
  2. Click the Delete button (🗑️) for that key
  3. Confirm deletion in the confirmation dialog

Deletion Precautions

  • Deleted keys are immediately invalidated
  • All API requests using that key will fail
  • Deletion cannot be undone

Pre-deletion Checklist

✅ Check before deleting:

  • Verify if any services are using this key
  • Generate a new key in advance and replace it
  • Confirm the key has been updated in all environments

Security Best Practices

Protecting API Keys

  1. Use Environment Variables
# .env file
FIRSTAGE_API_KEY=fak_your_api_key_here
  1. Don’t Commit to Git
# Add to .gitignore
.env
.env.local
.env.production
  1. Use Secrets Management Tools
  • AWS Secrets Manager
  • HashiCorp Vault
  • Google Secret Manager

Separate Keys per Environment

❌ Wrong way:

// Using same key for all environments
const API_KEY = 'fak_Abc123...';

✅ Correct way:

// Different keys per environment
const apiKey = {
  development: process.env.DEV_API_KEY,
  staging: process.env.STAGING_API_KEY,
  production: process.env.PROD_API_KEY,
}[process.env.NODE_ENV];

Regular Key Rotation

We recommend rotating API keys every 3-6 months for security.

Rotation procedure:

  1. Generate new API key
  2. Deploy new key to all services
  3. Delete old key after a grace period (e.g., 1 week)

Minimize Permissions

Grant only necessary permissions.

❌ Bad example:

// Granting all permissions
permissions: [
  'contents:read', 'contents:write',
  'schedules:read', 'schedules:write',
]

✅ Good example:

// Granting only necessary permissions
permissions: [
  'contents:read',
  'schedules:write',
]

If a Key is Exposed

If an API key has been exposed, take immediate action:

Immediate Actions

  1. Delete Key: Delete immediately in Developer Center
  2. Generate New Key: Issue a new API key
  3. Update Services: Deploy new key to all services
  4. Check Logs: Review for suspicious API activity

Preventing Exposure

  • Don’t commit keys to public repositories
  • Don’t share keys via Slack, email, etc.
  • Be careful not to show keys in screenshots
  • Don’t expose keys in client-side code

Troubleshooting

API Calls Failing

Symptom: 401 Unauthorized error

Causes:

  • Using incorrect API key
  • Key has been deleted or expired
  • Key format is incorrect

Solution:

  1. Verify API key is correct
  2. Check key status is “active”
  3. Verify key is correctly entered in X-API-Key header

Permission Errors

Symptom: 403 Forbidden error

Cause: Missing required permissions for the operation

Solution:

  1. Check if API key has required permissions
  2. If missing permissions, regenerate key or issue new one

Rate Limit Exceeded

Symptom: 429 Too Many Requests error

Cause: Exceeded hourly request limit

Solution:

  1. Check limit information in response headers
  2. Reduce request frequency
  3. Upgrade plan if higher limit is needed

Next Steps

Quick Start