API authentication and rate limits

Commercial API access should be scoped, metered, and rate-limited from the start.

API keys

API keys should be:

• Created inside an organisation.
• Shown once.
• Hashed at rest.
• Scoped by product.
• Revocable.
• Logged when used.

Scopes

First scopes:

• fragrance:read
• match:read
• similar:read
• widget:read
• feed:write
• mcp:read
• mcp:write

Rate limits

Limits should protect:

• Search endpoints.
• Fuzzy match.
• Gift finder.
• Feed enrichment.
• MCP tool calls.
• Image and note thumbnail serving.

Return quota errors that explain the plan, current usage, and upgrade path.

Metering

Record:

• Organisation.
• API key ID.
• Endpoint.
• Units used.
• Response status.
• Latency.
• Billing period.

This powers invoices, plan warnings, abuse detection, and investor-grade usage metrics.