Every integration answers one question before anything else: whose account is this running on?
That single decision determines whether you need your own credentials, whether you sign an agreement, and how you are charged.
The three provisioning models
| Model | Whose account | What you do |
|---|---|---|
| Shared | Ours | Accept an agreement. We provide the backend and meter your usage. |
| Sub-account | Ours, scoped to you | Accept an agreement. We provision you an isolated sub-account under our master. |
| Bring your own | Yours | Supply your own credentials, or connect your account over OAuth. |
Shared
The platform holds master credentials and runs the service on your behalf. You switch it on by accepting an agreement, and we meter what you use and bill it.
This is the fast path — no accounts to open, no keys to obtain, nothing to configure. It suits AI, email sending, SMS and shipping labels, where the service is a commodity and you have no reason to want a direct relationship with the provider.
Sub-account
Some providers natively support scoped sub-accounts. Where they do — Twilio being the clearest example — accepting the agreement provisions you your own isolated sub-account under our master account.
You get the convenience of shared provisioning with real isolation: your numbers, your logs and your usage are yours, not commingled with other tenants.
Bring your own
You supply the credentials. This is required, not optional, whenever:
- Money lands in your account. Payment providers must be yours — funds cannot route through ours.
- The account is inherently yours. Social profiles, ad accounts and online stores are connected over OAuth to accounts you already own.
Most shared services can be switched to your own credentials if you would rather go direct — because you already have volume pricing, a compliance requirement, or an existing relationship with the provider. Where that is possible, the integration is marked as allowing it.
Automatic fallback
An organization does not need to configure an integration before it works.
When a service is requested and your organization has no configuration for it, the platform falls back to the shared organization's configuration and runs the request on platform credentials.
This is why AI, email and messaging work on a new organization from the first minute rather than after a setup checklist.
Isolation is preserved on fallback
The fallback uses the shared organization's configuration, but the running instance is constructed and cached per tenant. Your requests do not share a connection or a client instance with another organization's.
The order of resolution is:
1. Your own configuration for that provider, if you have one.
2. A named default if you have several configurations for the same provider.
3. The shared organization's configuration, used with a tenant-isolated instance.
4. Failure — if none exists, the call fails rather than silently doing nothing.
If you have not supplied your own credentials, the request runs on ours and is charged to your balance with the platform markup applied. Supplying your own credentials moves the provider cost to your account with the provider. See Billing.
Switching from ours to yours
Adding your own credentials for a service you were using on fallback takes effect on the next call — your configuration is found first, so the fallback is no longer reached.
Nothing needs to be migrated, and there is no cutover window. Saving a configuration shuts down any cached instance for that provider so the next request builds a fresh one against your credentials.
Several configurations for one provider
You can hold more than one configuration for the same provider — a test account and a live one, or different accounts per brand — and mark one as the default. Calls that do not name a specific configuration use the default.
What an integration must implement
Every provider in the registry implements the same contract, which is what lets the console treat them uniformly:
| Method | Purpose |
|---|---|
init | Establish the connection |
doOperation | Perform a named operation |
test | Verify the configuration works |
shutdown | Close and release the connection |
preSave / postSave | Hooks that run around configuration changes |
Providers also declare a configuration schema, so the console renders the correct settings form without knowing anything specific about the provider, plus a description, help text and a list of the operations they support.
Testing a connection
A configuration can be tested before you rely on it. Testing runs against the real provider with the credentials you supplied, so a wrong key or an expired token surfaces immediately rather than during a customer's checkout.
Connection status is visible per integration, so an expired credential is apparent before it silently stops working.
Calling an integration directly
Beyond the features that use integrations internally, you can invoke a named operation on a configured integration yourself — useful for provider capabilities the platform does not surface as a feature.