API Provider Registration & Environment Keys

Standard Setup Workflow

1. Create provider account and complete verification/billing where required.
2. Generate API keys, OAuth client IDs, or webhook secrets in the provider dashboard.
3. Add values to production .env and local .env (never commit secrets).
4. Mirror credentials in Admin → Settings when the panel supports runtime overrides (Mail, Payment, AI, YouTube).
5. Test in sandbox/test mode, then switch to live keys.
6. Run php artisan optimize:clear then php artisan config:cache on the server.

OpenAI

Portal: platform.openai.com/api-keys

1. Sign up and add a payment method under Billing.
2. Create a new secret API key (copy immediately — shown once).
3. Optional: set organization ID if you use multiple orgs.

Used for images, text, and related AI features configured in Admin → Settings → AI.

xAI (Grok)

Portal: console.x.ai

1. Create account and open API keys section.
2. Generate API key and copy to XAI_API_KEY.

FAL.ai & Suno API

FAL.ai (video models: Kling, Veo, etc.)

Portal: fal.ai/dashboard/keys

Suno (music generation)

1. Register at your Suno API provider (e.g. sunoapi.org) and create an API key.
2. Generate your own webhook secret — Suno does not issue a webhook signing secret. You create a long random string and use it on both sides below.
3. Set SUNO_WEBHOOK_SECRET in .env to that value (required in production).
4. In the Suno provider dashboard, set the callback/webhook URL to the same secret as the token query parameter:

Generate a secret locally (example):

YouTube OAuth (Publishing)

Portal: Google Cloud Console → Credentials

1. Create a project (or select existing).
2. Enable YouTube Data API v3.
3. Configure OAuth consent screen (External, add test users during development).
4. Create OAuth 2.0 Client ID → type Web application.
5. Add authorized redirect URI exactly: https://yourdomain.com/dashboard/youtube/callback
6. Copy Client ID and Client Secret.

Cloudflare R2 Storage

Portal: Cloudflare Dashboard → R2

1. Create an R2 bucket (e.g. melodai-storage).
2. Create R2 API token with Object Read & Write on that bucket.
3. Copy Access Key ID, Secret Access Key, and account endpoint URL.
4. Optionally connect a custom domain for public CDN URL.

Stripe (Laravel Cashier)

Portal: dashboard.stripe.com/apikeys

1. Create Stripe account and complete business verification.
2. Copy Publishable key and Secret key (test mode first).
3. Developers → Webhooks → Add endpoint: https://yourdomain.com/stripe/webhook (Cashier default).
4. Select events Cashier needs (checkout, customer subscription, invoice).
5. Copy webhook signing secret.

Also enable Stripe in Admin → Settings → Payment.

Flutterwave

Portal: dashboard.flutterwave.com

1. Complete merchant verification.
2. Copy Public Key, Secret Key, and Encryption Key.
3. Set webhook URL and copy webhook hash.

Enable Flutterwave in Admin → Settings → Payment.

Revolut Merchant API

Portal: Revolut Merchant API (Business account → Merchant API). MelodAI uses API version 2026-04-20 for orders, webhooks, and refunds.

1. Create or open a Revolut Business merchant account and complete onboarding.
2. Generate API keys (public + secret). Start with sandbox.
3. Create a webhook endpoint on Revolut pointing to your MelodAI URL (HTTPS in production).
4. Copy the webhook signing secret (wsk_...).
5. Add keys to .env or Admin → Settings → Payment → Revolut (admin values override .env when saved).
6. Turn on Enabled and save. Revolut appears at checkout only when enabled and a secret key is configured.

Webhook & return URLs

The return URL runs after hosted checkout. Fulfillment also runs from webhooks when the order completes.

Environment variables

Set REVOLUT_ENVIRONMENT=production (or Production in admin) for live payments. Sandbox: https://sandbox-merchant.revolut.com; production: https://merchant.revolut.com.

Cryptomus (crypto payments)

Portal: cryptomus.com → Business → Merchant → API integration.

1. Register a Cryptomus merchant account and complete verification.
2. Copy Merchant UUID and Payment API key.
3. Set the payment webhook URL in Cryptomus to your MelodAI endpoint (HTTPS).
4. Add credentials to .env or Admin → Settings → Payment → Cryptomus.
5. Enable Enabled. Checkout shows Cryptomus when enabled and both UUID and payment key are set.

Webhook & return URLs

Cryptomus signs webhooks with an MD5 signature from your payment key; MelodAI verifies before fulfilling invoices or subscriptions.

Environment variables

Payment providers — activation checklist

MelodAI supports Stripe (Cashier), Flutterwave, Revolut, and Cryptomus. Configure in Admin → Settings → Payment or .env; admin-saved values override .env when present.

1. Set APP_URL and Admin → Settings → General → Site URL to your public HTTPS domain.
2. Register webhook URLs at each provider (see sections above).
3. Enable each provider toggle and save required keys.
4. Run sandbox/test checkout for subscriptions and credit packs from Dashboard → Billing.
5. Confirm invoice creation and entitlements (credits or active subscription).
6. For production, switch Revolut to production, Stripe to live keys, and Cryptomus/Flutterwave to live credentials.

Admin refunds

• Stripe: payment intent refund when allowed.
• Flutterwave: transaction refund API.
• Revolut: order refund API.
• Cryptomus: refund with admin-supplied wallet address; entitlements reversed on success.

Social Login (Google, GitHub, Discord)

Google

1. Google Cloud Console → OAuth client (Web).
2. Redirect URI: https://yourdomain.com/auth/google/callback

GitHub

github.com/settings/developers → OAuth App → Authorization callback URL https://yourdomain.com/auth/github/callback

Discord

discord.com/developers/applications → OAuth2 → Redirect https://yourdomain.com/auth/discord/callback

Leave blank to hide social login buttons (FEATURE_SOCIAL_LOGIN=true still requires keys).

Cloudflare Turnstile (Captcha)

Portal: Cloudflare Dashboard → Turnstile → Add site widget for your domain.

Prefer Admin → Settings → Security for runtime updates.

SMTP Email

Use your hosting mailbox or transactional provider (Brevo, Mailgun, Amazon SES).

Test from Admin → Settings → Mail → Send test email.

Pusher & Reverb (Real-Time)

Pusher (managed)

dashboard.pusher.com → Create app → copy app id, key, secret, cluster.

Reverb (self-hosted VPS)

See VPS documentation for generating REVERB_APP_KEY and REVERB_APP_SECRET.

Full .env Reference (MelodAI)

Core application and infrastructure variables from .env.example:

Feature flags:

Admin Settings Mapping

• General: Site name, Site URL (cron base), contact emails
• AI: OpenAI, xAI, Suno, FAL defaults
• Mail: SMTP host, port, credentials (overrides .env at runtime)
• Payment: Stripe, Flutterwave, Revolut, Cryptomus toggles and keys
• YouTube: OAuth client and redirect URI
• Security: Turnstile keys
• Cron & Queue: HTTP cron URLs and cPanel commands