Mandato — API Keys Setup

This is the provider-side runbook: for every external service Mandato can use, where to create the account, how to get the key, and exactly which environment variable to paste it into in Netlify (or .env.local for local development).

🔌 Two ways to configure most services. Several integrations (Claude, Resend, Recall, Stripe, Holded, OpenSanctions) can be set per firm inside the app — Settings → Integrations → … → Set up — with no environment variables at all. That in-app flow is documented in Integrations Setup. This file covers the deploy-level keys an administrator sets once for the whole deployment, and the provider sign-up steps behind every key.

🧪 Nothing here is required to try Mandato. With no keys, every feature runs on a realistic demo simulation. Add a key to switch that feature to live.

---

How Netlify environment variables work

1. Open the Netlify dashboard → your site (mandatocrm) → Site configuration → Environment variables.
2. Click Add a variable (or Add a single variable), enter the Key (e.g. ANTHROPIC_API_KEY) and the Value, and save.
3. Redeploy. Environment variables are read at build/runtime, so trigger Deploys → Trigger deploy → Deploy site for the change to take effect.

Variables prefixed NEXT_PUBLIC_ are exposed to the browser (build-time, public). Everything else is server-only and never reaches the client. Never put a non-public secret behind a NEXT_PUBLIC_ name.

Fallback order

For each integration Mandato resolves credentials as per-firm key (entered in the app) → system environment variable → demo simulation. So a deploy-level key acts as the default for every firm that hasn't entered its own.

---

0. Supabase (database, auth, storage) — required for live mode

Without these three, Mandato runs entirely in demo mode (in-memory data).

Variable	Where to get it
NEXT_PUBLIC_SUPABASE_URL	Supabase → Project → Settings → API → Project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	same page → Project API keys → anon public
SUPABASE_SERVICE_ROLE_KEY	same page → service_role (server-only; bypasses RLS — keep secret)
NEXT_PUBLIC_SITE_URL	your URL — http://localhost:3000 locally, https://app.mandato.es in production

Steps

1. Create a project at supabase.com.
2. Run the migrations in supabase/migrations/ (SQL editor) and seed.sql for demo data.
3. Copy the URL and both keys from Settings → API into Netlify.
4. After any schema change, run scripts/verify-rls.sql to confirm tenant isolation.

---

1. Google OAuth (Supabase sign-in)

This is the Continue with Google button on the login screen. It is configured in Supabase, not in Netlify.

Steps

1. In the Google Cloud Console, create or select a project.
2. APIs & Services → OAuth consent screen — configure it (External, app name, support email, your domain).
3. APIs & Services → Credentials → Create credentials → OAuth client ID → application type Web application.
4. Under Authorized redirect URIs, add the callback Supabase gives you: https://<your-project-ref>.supabase.co/auth/v1/callback.
5. Copy the Client ID and Client secret.
6. In Supabase → Authentication → Providers → Google, enable it and paste the Client ID and secret. Add your site URL and redirect URLs under Authentication → URL Configuration.

No Netlify variable is needed for sign-in itself — Supabase handles the exchange.

---

2. Google Maps / Places (address autocomplete)

Variable: NEXT_PUBLIC_GOOGLE_MAPS_API_KEY (public, build-time)

Steps

1. Open the Google Cloud Console → Maps credentials and create or select a project (you can reuse the OAuth project).
2. APIs & Services → Library — enable both Maps JavaScript API and Places API.
3. Credentials → Create credentials → API key and copy the AIza… key.
4. Restrict the key: Application restrictions → HTTP referrers, add your domains (https://app.mandato.es/*, http://localhost:3000/*). API restrictions → limit to Maps JavaScript + Places.
5. Paste into Netlify as NEXT_PUBLIC_GOOGLE_MAPS_API_KEY and redeploy.

Billing must be enabled on the Google Cloud project, but Maps has a generous free tier for this usage.

---

3. Claude / Anthropic (all AI features)

Variable: ANTHROPIC_API_KEY (server-only) — or per-firm via the app.

Steps

1. Sign in at console.anthropic.com → Settings → API Keys.
2. Create Key, name it Mandato, and copy it — it starts with sk-ant-.
3. Ensure the workspace has billing/credit configured, or live calls fail.
4. Paste into Netlify as ANTHROPIC_API_KEY, or per firm in Settings → Integrations → Claude AI → Set up.

Pricing: you pay Anthropic per token used. Mandato uses the claude-opus-4-8 model. Costs scale with usage (drafting, analysis, summaries); a small firm typically spends a few euros a month. Monitor usage in the Anthropic console.

---

4. OpenSanctions (AML / PEP / sanctions screening)

Variable: OPENSANCTIONS_API_KEY (server-only) — or per-firm via the app.

Steps

1. Create an account at opensanctions.org/account.
2. Find or request your API key on the account page — it starts with os_. (Commercial use requires a paid plan; check their licensing.)
3. Paste into Netlify as OPENSANCTIONS_API_KEY, or per firm in Settings → Integrations → OpenSanctions → Set up → Test key, then enable Auto-screen new clients and a re-screening interval.

---

5. 360dialog (WhatsApp Business)

Variables (deploy-level):

Variable	Value
WHATSAPP_API_KEY	the API key for your number from the 360dialog hub
WHATSAPP_WEBHOOK_VERIFY_TOKEN	a random string you choose; paste the same value into 360dialog

Steps

1. Create a partner account at hub.360dialog.com and onboard your WhatsApp Business number (firm-owned, not personal).
2. Generate an API key for the number in the hub.
3. Set WHATSAPP_API_KEY and a self-chosen WHATSAPP_WEBHOOK_VERIFY_TOKEN in Netlify and redeploy.
4. In Settings → Integrations → WhatsApp → Set up, copy the Webhook URL shown and paste it into the 360dialog dashboard, using the same verify token.
5. Use Send a test message to confirm the round trip.

The webhook endpoint is /api/webhooks/whatsapp. Inbound messages attach to the matching client and case.

---

6. Resend (transactional & campaign email)

Variable: RESEND_API_KEY (server-only) — or per-firm via the app.

Steps

1. Create an account at resend.com.
2. Verify your sending domain — add the DNS records Resend gives you (SPF, DKIM). Deliverability depends on this.
3. API Keys → Create API Key — it starts with re_. Copy it immediately (shown once).
4. Paste into Netlify as RESEND_API_KEY, or per firm in Settings → Integrations → Resend → Set up, then set the sender name and verified domain.

Resend powers welcome emails, invoice notices, reminders, NPS surveys and marketing campaigns.

---

7. Stripe (client payments + firm subscription)

Stripe is used two ways: clients paying your invoices (via Stripe Connect), and Mandato's own subscription billing.

Variables (deploy-level):

Variable	Where to get it
STRIPE_SECRET_KEY	Dashboard → Developers → API keys → Secret key (sk_…)
STRIPE_PUBLISHABLE_KEY / NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY	same page → Publishable key (pk_…)
STRIPE_WEBHOOK_SECRET	Developers → Webhooks → Add endpoint → signing secret (whsec_…)
STRIPE_CONNECT_CLIENT_ID	Settings → Connect → Platform settings (ca_…) — for firms paying via Connect
STRIPE_CONNECT_REDIRECT_URI	your Connect OAuth return URL
STRIPE_PRICE_PROFESSIONAL / STRIPE_PRICE_ENTERPRISE	Product catalog → Prices → price IDs (price_…) for the SaaS plans

Steps

1. Create/sign in at dashboard.stripe.com.
2. Copy the publishable and secret keys (use test mode keys until you go live).
3. Developers → Webhooks → Add endpoint → URL https://app.mandato.es/api/webhooks/stripe, select the relevant events (checkout, invoice, subscription lifecycle), and copy the signing secret into STRIPE_WEBHOOK_SECRET.
4. For client payments, enable Connect and copy the platform client ID.
5. Create your SaaS products/prices (Pro, Enterprise) and copy their price IDs.
6. Paste all of the above into Netlify and redeploy.

Firms can also connect their own Stripe account from Settings → Integrations → Stripe → Connect with Stripe (OAuth), so payments settle into the firm's account.

---

8. Recall.ai (meeting recording)

Variable: RECALL_API_KEY (server-only) — or per-firm via the app. Optional: RECALL_API_BASE to target a specific region.

Steps

1. Sign up at recall.ai and open the dashboard.
2. API Keys → create a key and copy it.
3. Paste into Netlify as RECALL_API_KEY, or per firm in Settings → Integrations → Recall.ai → Set up → Test connection.

A Recall bot joins meetings, records and transcribes; Claude then summarises and extracts action items.

---

9. Holded (accounting export)

Variable: HOLDED_API_KEY (server-only) — or per-firm via the app.

Steps

1. Sign in to Holded → Settings → Developers.
2. Under API key, generate or copy your key.
3. Paste into Netlify as HOLDED_API_KEY, or per firm in Settings → Integrations → Holded → Set up → Test connection → Connect → Sync now.

Holded stays the source of truth for invoices, VAT and SII — Mandato exports to it and mirrors invoices back, but never builds tax compliance itself.

---

10. Google Calendar (deadline sync)

This is an OAuth connection (the firm clicks Connect in-app), but it needs an OAuth client at deploy level.

Variables (deploy-level):

Variable	Value
GOOGLE_CLIENT_ID	OAuth client ID from Google Cloud
GOOGLE_CLIENT_SECRET	OAuth client secret
GOOGLE_REDIRECT_URI	https://app.mandato.es/api/integrations/google-calendar/callback

Steps

1. In the Google Cloud Console, enable the Google Calendar API (APIs & Services → Library).
2. Create an OAuth client ID (Web application) with the redirect URI above registered, and the Calendar scope on the consent screen.
3. Copy the client ID and secret into Netlify and redeploy.
4. The firm then connects from Settings → Integrations → Google Calendar → Connect — no key to paste.

Mandato manages only the events it creates; it does not read personal events.

---

11. Email — Gmail / Outlook OAuth (per-lawyer mailbox)

Optional native send/receive. The system inbox (BCC) fallback needs no keys and is the recommended compliance default.

Gmail (Google) variables:

Variable	Value
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	the same Google OAuth client (add Gmail scopes)
GOOGLE_EMAIL_REDIRECT_URI	https://app.mandato.es/api/integrations/gmail/callback

Outlook (Microsoft) variables:

Variable	Where to get it
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET	Azure Portal → App registrations → register an app, add a client secret
MICROSOFT_TENANT	your Azure AD tenant ID (or common)
MICROSOFT_REDIRECT_URI	https://app.mandato.es/api/integrations/outlook/callback

Steps (Gmail): add gmail.readonly and gmail.send scopes to your Google OAuth consent screen; register the email redirect URI; set the variables.

Steps (Outlook): in Azure, register an app, add Mail.Read and Mail.Send delegated permissions, create a client secret, and register the redirect URI.

Lawyers then connect from Settings → Integrations → Email.

---

12. CENDOJ (Spanish jurisprudence search) — optional

Variables: CENDOJ_API_KEY, optionally CENDOJ_API_BASE.

Used by Legal Research. Without a key, search runs against a built-in demo corpus. If you have access to a CENDOJ-compatible jurisprudence API, set the key and (if needed) the base URL in Netlify.

---

Quick reference — all deploy-level variables

# Core (Supabase)
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
NEXT_PUBLIC_SITE_URL=

# AI
ANTHROPIC_API_KEY=

# Address autocomplete (public)
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=

# Compliance
OPENSANCTIONS_API_KEY=

# WhatsApp (360dialog)
WHATSAPP_API_KEY=
WHATSAPP_WEBHOOK_VERIFY_TOKEN=

# Email delivery
RESEND_API_KEY=

# Payments + subscription (Stripe)
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=
STRIPE_CONNECT_CLIENT_ID=
STRIPE_CONNECT_REDIRECT_URI=
STRIPE_PRICE_PROFESSIONAL=
STRIPE_PRICE_ENTERPRISE=

# Meeting recording
RECALL_API_KEY=

# Accounting export
HOLDED_API_KEY=

# Google Calendar + Gmail OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=
GOOGLE_EMAIL_REDIRECT_URI=

# Outlook OAuth
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
MICROSOFT_TENANT=
MICROSOFT_REDIRECT_URI=

# Jurisprudence (optional)
CENDOJ_API_KEY=
CENDOJ_API_BASE=

🔐 Security. Only NEXT_PUBLIC_* variables are exposed to the browser. Keep SUPABASE_SERVICE_ROLE_KEY, STRIPE_SECRET_KEY and every other secret server-side. Never commit .env.local. Rotate any key that may have leaked from the provider's dashboard.

For the in-app, per-firm setup wizards (the easier path for most keys), see Integrations Setup.