ADR-017: Platform AI keys, and Magnific

Status: accepted 6 October 2026 (owner decision: use credentials from the environment for now).

Context

Every AI feature needed each shop to bring its own OpenAI and image-provider keys. Few florists have API keys, so in practice no shop could use AI. The owner holds platform keys and wants shops to have AI without setting anything up, for now.

Freepik’s API has been renamed Magnific:

• the docs at docs.freepik.com redirect to docs.magnific.com;
• the base URL is https://api.magnific.com, and the header is x-magnific-api-key;
• the endpoint paths are unchanged.

The old host still answers, with no announced end date.

Decision

1. Platform keys from the environment. config/ai.php reads AI_GLOBAL_CREDENTIALS, MAGNIFIC_API_KEY, MAGNIFIC_WEBHOOK_KEY, OPENAI_API_KEY and an optional MAGNIFIC_BASE_URL.

2. The shop’s own key wins. AiCredentials answers every “which key” question:

   • the shop’s enabled connection first;
   • otherwise the platform key, when global credentials are on and that key is set.

   The availability check, every generation endpoint and the service factory all ask it. Platform keys use each provider’s default models.

3. Settings → AI says when Flowery provides a service, so a shop knows it needs no key. Connecting its own key switches that shop to it.

4. Magnific.

   • The client calls api.magnific.com, sending the new header and, while the old host lives, the old one too.
   • The registry keeps the slug freepik, so saved connections stay valid. A migration renames what people see.

5. Secrets. Platform keys are redacted from provider error text like shop keys. They live only in the environment, never in the database or a page.

Consequences

• The platform pays for every generation by shops without their own keys. Nothing limits or records it per shop yet, beyond the 30-per-minute rate limit. Usage logging and plan limits come with billing.
• MAGNIFIC_WEBHOOK_KEY is configured but unused: generation still polls task status. Moving to Magnific’s signed webhooks (HMAC-SHA256 over id.timestamp.body) is a later change.
• Turning AI_GLOBAL_CREDENTIALS off takes AI away from every shop without its own key at once.
• Only the Seedream models work end to end today. Task status is always polled on the Seedream endpoint, so a shop that picks Mystic, Flux or HyperFlux as its default image model starts tasks it never collects. Platform keys use Seedream 4.5. The Flux Pro path was corrected to flux-pro-v1-1, as Magnific documents it, while checking the rename.