Developers
Build against the Homa Meta Platform integration layer
Technical reference for the OAuth flow, webhook handling, token lifecycle, permission model and error semantics used by Homa Meta Platform.
Homa Meta Platform sits between Meta’s business APIs and Homa CRM. This section documents how authorization is initiated, how tokens are held, how webhook events are verified, and how failures are surfaced. It is written for engineers integrating or reviewing the platform.
Reference topics
Each topic covers the intended design, the parts that depend on Meta approval, and the failure modes you should expect to handle.
OAuth flow
Authorization request construction, redirect URI handling, the state parameter, CSRF protection, and server-side authorization code exchange.
Read the OAuth referencePermission scopes
Least-privilege scope selection, the difference between standard and advanced access, App Review expectations, and reauthorization triggers.
Read the permissions referenceWebhooks
HTTPS endpoint requirements, the verification challenge, payload signature verification, deduplication, idempotency and retry behaviour.
Read the webhooks referenceAccess tokens
Short-lived and long-lived token concepts, encryption at rest, rotation, expiry handling, revocation and tenant isolation.
Read the tokens referenceData deletion
User-initiated deletion, the deletion request lifecycle, confirmation references, audit trail expectations and retention exceptions.
Read the deletion referenceError handling
Cancelled authorization, invalid state, missing permissions, expired tokens, revoked access, rate limits and upstream outages.
Read the error reference
Environment variables
Server-scoped values are read only in server code and are never sent to the browser. Values prefixed with NEXT_PUBLIC_ are inlined into the client bundle and must never hold a credential.
| NEXT_PUBLIC_SITE_URL | Public | Canonical origin for metadata, sitemap entries and absolute links. |
|---|---|---|
| NEXT_PUBLIC_HOMA_URL | Public | Destination for the “Open Homa CRM” navigation action. |
| META_AUTHORIZATION_BASE_URL | Server only | Host base of Meta’s authorization dialog (e.g. https://www.facebook.com). The full authorization URL is composed server-side from this plus the API version. When unset, /connect shows a configuration notice instead of starting a flow. |
| META_API_VERSION | Server only | Graph API version used to build the authorization dialog and token endpoints (e.g. v21.0). |
| META_APP_ID | Server only | Public app identifier sent as client_id in the authorization request server-side. |
| META_CONFIG_ID | Server only | Facebook Login for Business configuration id. Determines the scopes shown on Meta’s consent screen. |
| META_REDIRECT_URI | Server only | Exact redirect URI registered in the Meta app, with no trailing slash. Must point at /api/auth/meta/callback and match the registered value character for character. |
| META_APP_SECRET | Server only | Used only for server-side token exchange and webhook signature verification. Never exposed to the client and never logged. |
| HOMA_INTERNAL_API_URL | Server only | Backend endpoint the authorization result is delivered to for secure persistence. When unset, the callback returns storage_not_configured instead of faking a connection. |
| HOMA_INTERNAL_API_KEY | Server only | Bearer credential for the internal hand-off to the Homa backend. |
| META_WEBHOOK_VERIFY_TOKEN | Server only | Shared string compared during the webhook verification challenge. |
| RESEND_API_KEY | Server only | Enables delivery of contact and deletion request notifications. When unset, forms show an email fallback instead of claiming success. |
| DATA_DELETION_EMAIL | Server only | Inbox that receives data deletion requests. |
| CONTACT_EMAIL | Server only | Inbox that receives general contact submissions. |
Implementation principles
These constraints are applied throughout the integration layer and are worth mirroring in any client that consumes it.
Credentials stay server-side
The app secret and access tokens are read only in server code. No credential is placed in a client component, a URL, an error message or a log line.
Authorization is always server-initiated
The browser posts consent to a server route, which generates the state value, sets it as an HttpOnly cookie and issues the redirect. The client never assembles the authorization URL.
Unsigned webhook payloads are not trusted
Every delivery is verified against its signature before the body is parsed or acted upon. Verification failures are dropped and recorded, not retried blindly.
Every request is tenant-scoped
Stored assets and tokens carry a tenant identifier, and queries filter on it so one customer’s authorization can never resolve another customer’s data.
Failures degrade honestly
When a dependency is unconfigured or unavailable, the interface says so and offers a usable alternative. It does not report success for work that did not happen.
How to read feature status
The documentation labels each capability so you can tell what is running today from what depends on a Meta decision.
Start with the architecture overview
Getting Started covers the app configuration, required URLs and environment separation you need before your first authorization attempt.