Bring your own provider app

Koil is BYO-only for provider OAuth apps: every live-mode connection is authorized through a provider app your Organization owns and registers with Koil as an Auth Integration. Koil operates no shared or default provider apps.

Why BYO-only

• No shared-app blast radius. A shared provider app is a single point of failure — one tenant's policy strike can get the whole app suspended and take every customer offline. With your own app, provider enforcement is isolated to your tenant, and nobody else's behavior can interrupt your users.
• Your branding on the consent screen. End users see and approve your app when they authorize access, not a third-party integration layer.
• You own the token relationship. Grants are issued to your app, so adopting Koil never requires your users to re-authorize — and neither does leaving. There is no lock-in through credential ownership.

Koil manages everything downstream of the app: hosted Connect Sessions, credential storage and refresh, scope checks, Connection health, and Connected Profile resolution for every operation.

What you need (example: Instagram)

Each provider has its own developer-console prerequisites. For Instagram via Facebook Login you need:

• A Meta app in your Meta developer account, with business verification completed for your business portfolio.
• The permissions for the surfaces you use, approved through Meta App Review — request only what your product needs:
  • instagram_basic and pages_show_list — profile discovery and media reads.
  • pages_read_engagement — reading engagement on linked Pages.
  • instagram_manage_comments — comment events, moderation, and replies.
  • instagram_manage_messages — DM events and sends.
• Your app's credentials at hand: the OAuth client ID and client secret. Note that the app secret also signs your app's webhook deliveries, which is how Koil verifies provider events for your tenant.

The App Review playbook maps each Koil capability to the credential and permissions it requires, per provider, so you can scope your review request to exactly what you use. Its tables are generated from the same declarations that admit your grants at runtime, so what it says you need is what Koil checks.

The flow

1. Register an Auth Integration with your app's OAuth client ID, client secret, and scopes. Koil returns a stable int_* id and its webhookVerifyToken. A provider that needs your app's own id besides its client ID says so on GET /v1/providers (providerAppId: which auth provider, and where to find the id); pass it as providerAppId here, since it cannot be added afterwards.

   curl -X POST "https://api.koil.co/v1/auth-integrations" \  -H "Authorization: Bearer $KOIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "authProviderId": "facebook",  "displayName": "Acme Meta App",  "oauthClient": {    "clientId": "1234567890",    "clientSecret": "app-secret",    "scopes": [      "instagram_basic",      "pages_show_list",      "pages_read_engagement"    ]  }}'

2. Run Connect Sessions against your app. Create Connect Sessions with your authIntegrationId; the returned authorizationUrl sends your end user through your app's consent screen. Completed sessions yield Connections, from which you create Connected Profiles.

3. Point your app's webhooks at Koil. In the provider developer console, set each webhook object's callback URL to https://<koil-api>/webhooks/providers/{providerId}?authIntegrationId={authIntegrationId} and enter the Auth Integration's webhookVerifyToken (returned by POST and GET /v1/auth-integrations/…) as the verify token. Use one URL per Koil provider your app can authorize: for a Meta app, instagram, facebook, and whatsapp. Koil answers the console's verification handshake against that token, verifies every delivery with your app secret, normalizes it, and delivers it to your Event Destinations as content.* events. A TikTok API for Business app needs no console step: Koil registers the callback URL with TikTok through the webhook API itself, for each event family an Event Destination of yours is actually subscribed to for a TikTok Connected Profile under that app, removing it again when none is — and verifies each delivery's tiktok-signature with your app secret. If your app already points an event family somewhere else, Koil reports the conflict and leaves your callback alone. TikTok publishing additionally requires the media host to be a URL property your app has verified, which is not yet satisfiable — see the note on the TikTok page. A YouTube (Google Cloud) app has no webhook step at all: YouTube publishes no comment webhooks, so Koil polls, and the only console work is enabling the YouTube Data API, verifying the consent screen for the youtube.force-ssl scope, and passing the YouTube compliance audit if you need public uploads.

Rotate compromised secrets with POST /v1/auth-integrations/{authIntegrationId}/rotate-secret; see the API endpoints for the full contract.

Google Business Profile needs no webhook step at all: Google publishes review notifications to a Cloud Pub/Sub topic rather than to an HTTP callback, so Koil polls, and there is no /webhooks/providers/google_business_profile URL to enter anywhere.

A LinkedIn app registers its webhook by hand, and only once it has Community Management Standard Tier (Development Tier has push notifications switched off): in the Developer Portal's Webhooks tab, enter https://<koil-api>/webhooks/providers/linkedin?authIntegrationId={authIntegrationId}. LinkedIn validates the URL with a challenge Koil answers with your app's client secret, and repeats the challenge every two hours for as long as the URL is registered. Notifications for a Page then need an event subscription for that Page and the admin who connected it, which Koil makes when the Page is connected, provided that admin holds the Page's ADMINISTRATOR role. LinkedIn keys each subscription by your app's developer application id, the number in the app's Developer Portal URL (https://www.linkedin.com/developers/apps/{id}/…), which is not the OAuth client ID and which no API returns, so a LinkedIn Auth Integration takes it as providerAppId when you create it.

Google Business Profile: apply before you build

Google Business Profile is the one provider whose gate comes before the first call rather than before going live, so plan for it earlier than the rest.

Every other provider lets you enable an API and start calling immediately, with review standing between you and public or large-scale use. Google caps a Cloud project at zero queries per minute until it approves an application for Business Profile API access — so an unapproved project cannot make a single request, and there is no sandbox and no read-only lane to develop against.

To apply you need a Google Business Profile that is verified and active for at least 60 days, a website representing that business, a complete and current profile, a Google Cloud project, and an Organization account. The application is the Business Profile API contact form ("Application for Basic API Access"), filed from an email listed as an owner or manager on the profile. Google publishes no turnaround time. Your project's quota is the signal: 0 QPM means the application is still pending, 300 QPM means it was granted.

Two things gate replying specifically, beyond the scope: the location must be verified, and in a Google Workspace tenant your admin must have enabled Google Search and/or Google Maps.

Koil's test mode does not depend on any of this — build the whole integration against test_conn_google_business_profile_healthy while the application is in flight.

Integrate today, go live when review completes

You do not need a provider app — or an approved permission set — to start integrating. Test-mode API keys exercise the same endpoints, schemas, events, and error contracts as live mode, with simulated provider behavior and a catalog of magic connections (such as test_conn_instagram_healthy or test_conn_instagram_expired) standing in for real Connections. No OAuth flow, no consent screen, no app review.

That makes the onboarding path: build your full integration in test mode now, run provider app review in parallel, then register your approved app as an Auth Integration and switch to a live key to go live.