Authentication

API Key Format

All MockHero API keys share the same format: mh_ followed by 32 hexadecimal characters. There is no distinction between test and production keys.

Keys are 35 characters long including the prefix. They contain lowercase hex characters (0-9, a-f).

Sending Your Key

Include your API key in every request using one of the two supported header formats. Both are equivalent; use whichever fits your HTTP client.

Option 1: Authorization Bearer Recommended

Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

Option 2: x-api-key Header

x-api-key: mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0

Full Request Example

curl -X POST https://api.mockhero.dev/api/v1/generate \
  -H "Authorization: Bearer mh_7a1c3b24f8d4e6a9b2c1d3e5f7a8b9c0" \
  -H "Content-Type: application/json" \
  -d '{ "template": "ecommerce", "scale": 1 }'

Getting an API Key

API keys are managed from your MockHero dashboard.

1. Sign up or sign in at mockhero.dev/sign-up.
2. Navigate to Settings → API Keys.
3. Click Create Key.
4. Copy the key immediately. For security, the full key is only shown once.

Key Rotation

If a key is compromised or you want to rotate keys as a security practice, you can revoke and replace keys without downtime.

1. Create a new key from the dashboard before revoking the old one.
2. Update your application or CI environment to use the new key.
3. Verify the new key works by making a test request.
4. Revoke the old key from Settings → API Keys. The old key will immediately return 401 Unauthorized.

Authentication Errors

If your key is missing, malformed, or revoked, the API returns one of these responses.

401 Unauthorized — Missing or Invalid Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is missing or invalid. Include a valid key in the Authorization header."
  }
}

403 Forbidden — Key Lacks Permission

{
  "error": {
    "code": "FEATURE_REQUIRES_UPGRADE",
    "message": "Schema detection requires Pro tier or above. Upgrade at https://mockhero.dev/pricing"
  }
}