API Keys

API keys authenticate your reporters and integrations with Spekra. This guide covers creating, managing, and securing your API keys.

Creating an API Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Enter a descriptive name (e.g., "CI Pipeline", "Local Development")
4. Click Create
5. Copy the key immediately - it won't be shown again

API Key Format

Spekra API keys follow this format:

sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Always start with sk_ (secret key)
• 32 characters of random alphanumeric data
• Case-sensitive

Using API Keys

In Reporter Configuration

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
}]

In Environment Variables

export SPEKRA_API_KEY=sk_your_api_key_here

In CI Secrets

Store your API key as a secret in your CI provider:

Key Permissions

Currently, all API keys have full write access to your organization. They can:

• Submit test results
• Create test runs
• Update test metadata

API keys cannot:

• Access other organizations' data
• Modify team settings
• Create or delete other API keys

Best Practices

Use Descriptive Names

Name keys by their purpose:

• ✅ "GitHub Actions - Main Repo"
• ✅ "Local Dev - John's Machine"
• ❌ "key1"
• ❌ "test"

One Key Per Environment

Create separate keys for:

• Production CI
• Staging CI
• Local development

This allows you to revoke individual keys without affecting others.

Rotate Regularly

Rotate API keys periodically:

1. Create a new key
2. Update your configuration
3. Verify the new key works
4. Delete the old key

Never Commit Keys

If you accidentally commit a key:

1. Revoke it immediately in Spekra
2. Remove it from git history
3. Create a new key

Revoking Keys

To revoke an API key:

1. Go to Settings → API Keys
2. Find the key to revoke
3. Click the Delete button
4. Confirm deletion

Revoked keys stop working immediately. Any reporters using that key will fail to authenticate.

Troubleshooting

"Invalid API Key" Error

• Verify the key is correct (no extra spaces)
• Check the key hasn't been revoked
• Ensure you're using the right organization's key

"Unauthorized" Error

• The key may have been deleted
• Check if the key was copied correctly
• Verify the SPEKRA_API_KEY environment variable is set

Key Not Working in CI

• Ensure the secret is properly configured
• Check secret name matches your config
• Verify the secret is available to the workflow/job

Next Steps

• Playwright setup - Configure your first reporter
• CI/CD integration - Set up reporting in CI
• Troubleshooting - Common issues