Skip to main content

Obtaining API Keys

Step-by-step instructions for getting real credentials for every external provider Closegram integrates with. See Environment Setup for which .env variable each value goes into.

Providers are ordered roughly by how likely you are to need them for local development.

Database & Redis​

No account needed — see Local infrastructure via Docker. Only set up a managed Postgres/Redis provider (e.g. Railway, RDS, ElastiCache) when deploying.

LiveKit​

Local development: no account needed — the Docker Compose stack runs a real LiveKit server with a hardcoded dev key (devkey / dev1234567890abcdef1234567890abcdef). Point LIVEKIT_URL at ws://localhost:7880 and use those credentials.

Production: either self-host (deploy the same livekit/livekit-server image somewhere reachable, generate your own keypair with livekit-server generate-keys) or use LiveKit Cloud:

  1. Sign up at cloud.livekit.io and create a project.
  2. Go to Settings → Keys, create a new API key/secret pair.
  3. Copy the WebSocket URL, API Key, and API Secret into LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET.

Firebase​

Used for: Google Sign-In token verification (backend), push notifications (backend + iOS + web), and Firebase Auth on the frontend/iOS clients.

  1. Go to the Firebase console and create a project (or use an existing one).
  2. Backend service account (fills the FIREBASE_* backend variables): Project settings (gear icon) → Service accounts → Generate new private key. This downloads a JSON file — map its fields directly to FIREBASE_PROJECT_ID, FIREBASE_PRIVATE_KEY_ID, FIREBASE_PRIVATE_KEY, FIREBASE_CLIENT_EMAIL, FIREBASE_CLIENT_ID, FIREBASE_AUTH_URI, FIREBASE_TOKEN_URI, FIREBASE_AUTH_PROVIDER_CERT_URL, FIREBASE_CLIENT_CERT_URL. When pasting FIREBASE_PRIVATE_KEY into a .env file, keep it as a single line with literal \n sequences (matching the format already in .env.example).
  3. Web app config (fills the NEXT_PUBLIC_FIREBASE_* frontend variables): Project settings → General → scroll to Your apps → add a Web app (</> icon) if one doesn't exist → copy the firebaseConfig object's apiKey, authDomain, projectId, storageBucket, messagingSenderId, appId.
  4. iOS app config (fills GoogleService-Info.plist): Project settings → General → Your apps → add an iOS app with the bundle ID from app.xcodeproj → download GoogleService-Info.plist and replace apps/ios/app/app/GoogleService-Info.plist.
  5. Enable the sign-in methods you need under Authentication → Sign-in method (Google, and Phone if you want Firebase-based phone auth in addition to the Twilio/SMS path).
  6. If using push notifications, also enable Cloud Messaging under Project settings — no extra key needed beyond the service account above.

Google Sign-In (OAuth Client)​

Separate from the Firebase project above — this is a raw Google Cloud OAuth client, used by two different code paths in the backend (GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET for one strategy, CLIENT_ID/CLIENT_ID_SECRET/REDIRECT_URIs for another).

  1. Go to Google Cloud Console → select the same project as your Firebase project (Firebase projects are GCP projects under the hood) or create a new one.
  2. APIs & Services → OAuth consent screen — configure it (External, add your app name/support email) if not already done.
  3. APIs & Services → Credentials → Create Credentials → OAuth client ID.
  4. Application type Web application. Add your redirect URI(s) (e.g. http://localhost:8000/auth/google/callback for local dev) — this value also goes into REDIRECT_URIs.
  5. Copy the generated Client ID and Client Secret — use the same pair for both GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET and CLIENT_ID/CLIENT_ID_SECRET unless you specifically want them to be different apps.

Apple Sign-In​

Requires a paid Apple Developer account ($99/yr).

  1. Apple Developer → Certificates, Identifiers & Profiles → Identifiers → your App ID (or create one) → enable the Sign In with Apple capability.
  2. Identifiers → + → Services IDs → create one (e.g. com.yourapp.signin) → enable Sign In with Apple → configure it with your domain and redirect URL. This Services ID value is your APPLE_CLIENT_ID.
  3. Keys → + → check Sign In with Apple, configure it against your App ID → Continue → Register → Download. The download is a one-time-only .p8 file — its contents go into APPLE_PRIVATE_KEY (keep the -----BEGIN PRIVATE KEY----- / -----END PRIVATE KEY----- wrapper, \n-escaped like the other multiline keys). The Key ID shown on that page is APPLE_KEY_ID.
  4. Your Team ID is shown in the top-right of the Apple Developer account page (or under Membership) — that's APPLE_TEAM_ID.
  5. APPLE_REDIRECT_URI is the callback URL you configured on the Services ID in step 2 (only used for the web/backend OAuth flow — native Sign in with Apple on iOS doesn't need it).

The iOS app itself needs the Sign In with Apple capability added in Xcode (Signing & Capabilities) — already present in apps/ios/app/app/app.entitlements.

Apple Push Notifications (APNs)​

Separate key from Sign in with Apple — used for VoIP push (incoming call alerts) and standard iOS push.

  1. Apple Developer → Keys → + → check Apple Push Notifications service (APNs) → Continue → Register → Download. Again, this .p8 is downloadable only once.
  2. The key's contents go into APNS_PRIVATE_KEY; the Key ID shown on the page is APNS_KEY_ID.
  3. APNS_TEAM_ID is the same Team ID as above.
  4. APNS_BUNDLE_ID is your iOS app's bundle identifier (from app.xcodeproj).
  5. Leave APNS_PRODUCTION=false for a Debug/TestFlight build using the sandbox APNs environment; set to true for App Store builds.

Stripe​

  1. Sign up at dashboard.stripe.com.
  2. Developers → API keys — copy the Secret key (sk_test_... while in test mode) into STRIPE_API_KEY_PROD_SECRET, and the Publishable key (pk_test_...) into the frontend's NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY and iOS's STRIPE_PUBLISHABLE_KEY.
  3. Developers → Webhooks → Add endpoint — point it at <API_URL>/webhooks/stripe (or wherever the backend exposes it), select the events the app needs (payment intents, subscription events), then copy the Signing secret into STRIPE_WEBHOOK_SECRET. For local testing, the Stripe CLI (stripe listen --forward-to localhost:8000/webhooks/stripe) prints a webhook secret you can use instead.
  4. Switch to live keys (sk_live_... / pk_live_...) only in production, after completing Stripe's account activation.

AWS (S3, SES, SNS)​

  1. Create an AWS account if you don't have one, and sign in to the IAM console.
  2. Create an IAM user (or role) with programmatic access. Attach policies scoped to what you need: AmazonS3FullAccess (or a bucket-scoped custom policy), AmazonSESFullAccess, AmazonSNSFullAccess — narrow these down for production.
  3. IAM → Users → your user → Security credentials → Create access key — copy the Access key ID and Secret access key into AWS_ACCESS_KEY/AWS_ACCESS_KEY_ID and AWS_SECRET_KEY/AWS_SECRET_ACCESS_KEY (both naming variants are read by different parts of the codebase — use the same values for both).
  4. S3 bucket: S3 console → Create bucket, name it, note the region. Fill AWS_BUCKET_NAME and AWS_REGION; AWS_S3_URL is https://<bucket>.s3.amazonaws.com.
  5. SES (email): SES console → Verified identities → Create identity — verify a domain or individual sender email. While in the SES sandbox you can only send to verified addresses; request production access to send to any address. Set AWS_EMAIL to your verified sender.
  6. SNS (SMS, only if using SMS_PROVIDER=aws-sns): no separate signup — the same IAM credentials work; SNS is pay-as-you-go per SMS.
  7. For local development without any of this, set DISABLE_S3=true and DISABLE_EMAIL=true.

Twilio (SMS / phone OTP)​

Default SMS_PROVIDER.

  1. Sign up at twilio.com.
  2. Console dashboard shows your Account SID and Auth Token directly → TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN.
  3. Phone Numbers → Buy a number (trial accounts get one free) → copy it into TWILIO_PHONE_NUMBER.
  4. Verify → Services → Create new Service — this powers OTP codes specifically. Copy the Service SID into TWILIO_VERIFY_SERVICE_SID.
  5. For local development without SMS, set DISABLE_SMS=true.

MessageBird (alternative SMS provider)​

Only needed if you set SMS_PROVIDER=messagebird.

  1. Sign up at messagebird.com.
  2. Developers → API access → copy your Live API key (or Test key for sandbox) into MESSAGEBIRD_API_KEY.
  3. MESSAGEBIRD_ORIGINATOR is the sender name/number shown to recipients.

PayPal​

  1. Sign up for a PayPal Developer account.
  2. Apps & Credentials → Create App (under Sandbox for testing, Live for production).
  3. Copy the Client ID and Secret into PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET.
  4. PAYPAL_API_BASE defaults to the sandbox URL (https://api-m.sandbox.paypal.com) — switch to https://api-m.paypal.com for live.

In-app purchases (Apple & Google IAP)​

For selling coins inside the native apps. See Coins → Native in-app purchases for how it works, and the env vars.

Apple (App Store Server API)​

  1. First create the products: App Store Connect → your app → Monetization → In-App Purchases → Create a Consumable per coin package. Set its localized price tiers there (Apple localizes automatically), and copy each Product ID into its coin package in the admin /coins screen (appleProductId).
  2. Create an API key: App Store Connect → Users and Access → Integrations (Keys) → App Store Connect API → generate a key with the In-App Purchase (or Admin) role. Download the .p8 (once only).
  3. Map to env: the page shows the Issuer ID → APPLE_IAP_ISSUER_ID; the key's Key ID → APPLE_IAP_KEY_ID; the .p8 contents → APPLE_IAP_PRIVATE_KEY; your bundle id → APPLE_IAP_BUNDLE_ID.
  4. Notifications (refunds): App Store Connect → your app → General → App Store Server Notifications → Version 2, set the Production/Sandbox URL to https://<your-api>/api/webhooks/apple/iap. To pin the signature, download Apple Root CA — G3 from Apple PKI and put its PEM in APPLE_IAP_ROOT_CERT (required — the Apple refund webhook fails closed and rejects notifications without a pinned root).

Google (Play Developer API + RTDN)​

  1. First create the products: Play Console → your app → Monetize → Products → In-app products → Create a managed product per coin package. Copy each Product ID into its coin package in admin (googleProductId). GOOGLE_IAP_PACKAGE_NAME is your app's applicationId.
  2. Service account: in Google Cloud Console create a service account + JSON key; then in Play Console → Users and permissions → invite that service account and grant View financial data / Manage orders and subscriptions. Put the JSON (stringified) in GOOGLE_IAP_SERVICE_ACCOUNT_KEY.
  3. Refunds (Voided Purchases + RTDN): enable Play Console → Monetization setup → Real-time developer notifications, point the topic at a Google Cloud Pub/Sub topic, and add a push subscription to that topic delivering to https://<your-api>/api/webhooks/google/rtdn. To verify the push, set GOOGLE_RTDN_AUDIENCE (your webhook URL) and GOOGLE_RTDN_SA_EMAIL (the Pub/Sub push service account) — optional but recommended.

Google Cloud Vision (image moderation)​

Used for NSFW/content-label detection (IMAGE_ANALYSIS_PROVIDER=google-vision). Uses the same kind of service-account credentials as BigQuery below — you can reuse one service account for both if it has both APIs enabled.

  1. In Google Cloud Console, enable the Cloud Vision API for your project (APIs & Services → Library → Cloud Vision API → Enable).
  2. IAM & Admin → Service Accounts → Create Service Account, grant it a role like Cloud Vision AI Service Agent (or broader if reusing for BigQuery).
  3. Keys → Add key → Create new key → JSON — download it. The backend's image-analysis service picks up credentials the standard Google Cloud way; check services/image-analysis/image-analysis.service.js for exactly which env var(s) it expects the credentials path/JSON in before wiring this up, since it isn't one of the explicitly-named .env.example variables.

BigQuery (analytics, optional)​

Only needed if you set ANALYTICS_DB_TYPE=bigquery — the default (postgres) needs no external account at all.

  1. In Google Cloud Console, enable the BigQuery API.
  2. IAM & Admin → Service Accounts → Create Service Account, grant it BigQuery Data Editor and BigQuery Job User.
  3. Keys → Add key → Create new key → JSON — map the downloaded file's fields to BIGQUERY_PRIVATE_KEY_ID, BIGQUERY_PRIVATE_KEY, BIGQUERY_CLIENT_EMAIL, BIGQUERY_CLIENT_ID.
  4. BigQuery console → Create dataset — note the dataset ID and location for BIGQUERY_DATASET_ID / BIGQUERY_LOCATION.
  5. GOOGLE_CLOUD_PROJECT_ID / GCP_PROJECT_ID is your GCP project ID, visible on the Cloud Console dashboard.

Giphy (iOS GIF picker)​

  1. Sign up at developers.giphy.com.
  2. Create an App → choose the API key type (not SDK).
  3. Copy the key into iOS's GIPHY_API_KEY (Xcode scheme environment variable — see Environment Setup).

Observability (all optional)​

These only matter once you care about production monitoring — skip them entirely for local development.

  • Sentry — create a project, copy the DSN from Project Settings → Client Keys into SENTRY_DSN.
  • Datadog — Organization Settings → API Keys → create/copy one into DATADOG_API_KEY.
  • New Relic — Account settings → API keys → copy an Ingest - License key into NEW_RELIC_LICENSE_KEY.
  • LogRocket — Project Settings → copy the App ID (format org/project) into LOGROCKET_APP_ID.
  • Custom logger (CUSTOM_LOGGER_URL / CUSTOM_LOGGER_API_KEY) — only relevant if you're pointing logs at your own ingestion endpoint; not tied to a specific third-party product.