Security and Management

Security Best Practices

1. Store API Keys Securely

DO:

• Store API keys in environment variables
• Use secrets management services (AWS Secrets Manager, Azure Key Vault, etc.)
• Use different keys for different environments
• Rotate keys regularly (every 90 days recommended)

DON'T:

• Commit API keys to version control
• Hardcode API keys in source code
• Share API keys via email or chat
• Expose API keys in client-side code

2. Environment Separation

Use different API keys for:

• Development/Testing: Test environment keys
• Staging: Staging environment keys
• Production: Production environment keys

This allows you to:

• Revoke test keys without affecting production
• Monitor usage per environment
• Limit blast radius if a key is compromised

3. Key Rotation

Regularly rotate your API keys:

1. Create a new API key in Studio
2. Update your backend to use the new key
3. Test that everything works with the new key
4. Delete the old API key

Rotation Schedule: Rotate keys every 90 days, or immediately if you suspect a key has been compromised.

4. Monitor Usage

• Review API key usage in your logs
• Set up alerts for unusual activity
• Monitor for authentication failures
• Track which services are using which keys

5. Least Privilege

• Create separate API keys for different services if needed
• Use descriptive names to identify key purpose
• Delete unused API keys

Managing API Keys

Viewing API Keys

In Stash Studio → Project Settings → API Secrets:

• View all API keys for your shop
• See when each key was created
• See the key name/description

Deleting API Keys

1. Navigate to Project Settings → API Secrets
2. Find the API key you want to delete
3. Click the delete button
4. Confirm deletion

Regenerating API Keys

If you need to regenerate an API key:

1. Create a new API key
2. Update your backend to use the new key
3. Test the new key
4. Delete the old key

There's no "regenerate" option - you must create a new key and delete the old one.

Error Handling

Common Authentication Errors

Unauthenticated (401)

Error: invalid auth or X-Stash-Api-Key header is required

Causes:

• API key header is missing
• API key header is empty

Solution:

• Ensure the X-Stash-Api-Key header is included in your request
• Verify the header name is exactly X-Stash-Api-Key (case-sensitive)

Permission Denied (403)

Error: invalid key or PermissionDenied

Causes:

• API key is invalid or has been deleted
• API key doesn't belong to the shop specified in the request
• API key has been rotated and the old key is being used

Solution:

• Verify the API key secret is correct (copy from Studio)
• Ensure the API key belongs to the correct shop
• Check if the key was recently rotated and update your code

Example Error Response

{
  "error": {
    "code": 16,
    "message": "invalid key",
    "details": []
  }
}

Troubleshooting

API Key Not Working

1. Verify the key exists: Check Studio → API Secrets
2. Check the secret value: Ensure you copied the full secret
3. Verify header format: Must be exactly X-Stash-Api-Key
4. Check shop match: Ensure the key belongs to the shop in your request
5. Test with cURL: Use a simple cURL command to isolate the issue

Key Was Deleted Accidentally

If you accidentally deleted an API key:

1. Create a new API key in Studio
2. Update all services using the old key
3. Test thoroughly
4. There's no way to recover a deleted key

Multiple Keys for Same Shop

You can have multiple API keys for the same shop. This is useful for:

• Different environments (test, staging, production)
• Different services (checkout service, payment service)
• Key rotation (old and new keys during transition)

All keys for the same shop have the same permissions - they're not scoped to specific operations.

Related Documentation

• API Keys Overview
• Using API Keys
• Common Pitfalls
• Project Settings
• Stash Pay Authentication
• Stash Webshop Authentication
• Stash Launcher Authentication
• API Reference