Documentation/Integrations/Managed Integrations & Provider Catalog

Managed Integrations & Provider Catalog

Browse and wire up dozens of managed third-party providers — payments, messaging, identity, and data services — through one import, configure, execute lifecycle instead of hand-rolling an HTTP client for every vendor.

Overview

The managed services catalog is the primary way to connect a Supero app to a third-party provider. Instead of writing HTTP client code, storing credentials yourself, and handling retries, you import a catalog entry into your project, configure it with your provider credentials, and call it with one wire primitive: POST /api/v1/services/execute. The catalog spans roughly 38 providers across payments, messaging, identity and SaaS, and data — this page is a reference for what is in it and how to wire each one up.

This page assumes you are already familiar with importing and calling services in general — see the Transactional Services page for the underlying extends model, the state machine, and the shared execute contract. What is specific to this page is the external-provider half of the catalog: the providers here call out to a real third party (Stripe, Twilio, SendGrid, Okta, and so on) rather than mutating your own app data directly.

•Payments — Stripe, PayPal, Razorpay, PhonePe, Apple Pay, Google Pay, Plaid
•Messaging & notifications — SendGrid, SMTP, Twilio SMS/WhatsApp, Slack, push notifications, OTP
•Identity & SaaS — Okta, Salesforce, ServiceNow, QuickBooks, Google Workspace, GitHub, Bitbucket
•Data & observability — Datadog, Google Programmable Search, Amazon S3
•AI — call OpenAI or Anthropic directly using your own provider key
•Social & marketing — Instagram, Facebook, TikTok, X, LinkedIn, Google Ads, Google Business Profile (each requires the provider's own business/app verification before you can go live)

The Provider Catalog

Every entry below is a service_id you can pass to the import/configure/execute calls in the next section. Browse the live, authoritative list at any time with GET https://api.supero.dev/api/v1/services/catalog, or GET .../api/v1/services/catalog/{service_id} for one entry's full schema, operations, and config fields.

Payments

service_id	Provider	What it is for
billing	Stripe	Charges, customers, subscriptions, invoices.
stripe_checkout	Stripe	Hosted checkout sessions and payment links.
apple_pay	Stripe-backed	Apple Pay, processed through your Stripe account.
google_pay	Stripe-backed	Google Pay, processed through your Stripe account.
billing_paypal	PayPal	PayPal Checkout — orders, captures, refunds.
billing_razorpay	Razorpay	UPI, cards, wallets, and net-banking.
billing_phonepe	PhonePe	PhonePe hosted checkout.
plaid	Plaid	Bank account linking and verification.

Messaging & notifications

service_id	Provider	What it is for
email	SendGrid	Transactional email.
email_smtp	Any SMTP host	Transactional email over your own SMTP server.
sms	Twilio	SMS.
whatsapp	Twilio	WhatsApp messages and templates.
slack	Slack	Post messages and create channels in a workspace.
push_notification	FCM	Mobile push notifications, single-device or topic broadcast.
auth_otp	Configurable OTP provider	One-time-passcode issue/verify flows for login or step-up auth.

Identity & SaaS

service_id	Provider	What it is for
okta	Okta	Identity/SSO administration.
salesforce	Salesforce	CRM records — leads, contacts, opportunities.
servicenow	ServiceNow	ITSM records — incidents, requests.
quickbooks	Intuit QuickBooks	Accounting — invoices, customers, payments.
google_oauth	Google	Sign-in and token exchange for your users.
google_calendar	Google	Read/write events on a shared calendar.
google_drive	Google	Read/write files in a shared Drive folder.
youtube	YouTube Data API	Read channel/video data; uploads with OAuth.
github	GitHub	Repos, issues, and pull requests.
bitbucket	Bitbucket Cloud	Repos and pull requests (Cloud only).

Data & observability

service_id	Provider	What it is for
datadog	Datadog	Send custom metrics and events.
google_search	Google Programmable Search	Public web search results.
amazon_s3	AWS S3	Object storage in a bucket you own.

AI

The ai entry lets your app call OpenAI or Anthropic directly with a key you provide — see Bring Your Own AI Provider Key below.

Social & marketing

instagram, facebook, tiktok, x_social, linkedin, google_ads, and google_reviews are in the catalog too, but each sits behind the provider's own business verification or app-review process — see Providers That Require Business Verification below before you plan a launch around one.

Import, Configure, Execute

Every catalog entry follows the same three-step lifecycle, regardless of provider. First, import the service into your project — this links its schemas and registers it as available. Second, configure it with your provider credentials. Third, execute one of its operations. The same POST /api/v1/services/execute endpoint you'd use for an internal transactional service works identically here — the only difference is that the handler behind the scenes makes a real outbound call to the provider and writes a small tracking record for the attempt.

1. Import the service

bash

curl -X POST https://api.supero.dev/api/v1/services/import \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "email",
    "domain": "acme-corp",
    "project_uuid": "8f2a1c40-...",
    "config_data": {
      "sendgrid_api_key": "SG.xxxxxxxxxxxx"
    }
  }'

json

{
  "success": true,
  "service_id": "email",
  "namespace": "email",
  "service_registry_uuid": "b1c2...",
  "service_import_uuid": "d3e4...",
  "service_config_uuid": "f5a6...",
  "schemas_linked": [],
  "plugins_registered": ["email-sendgrid-gateway"],
  "error": null
}

2. Configure or update credentials

PUT to a service's /config endpoint at any time to add or rotate credentials — config_data is merged into what's already stored, so you only need to send the fields you're changing.

bash

curl -X PUT https://api.supero.dev/api/v1/services/email/config \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config_data": {
      "sendgrid_api_key": "SG.xxxxxxxxxxxx",
      "default_from_email": "[email protected]",
      "sandbox_mode": true
    }
  }'

3. Execute an operation

bash

curl -X POST https://api.supero.dev/api/v1/services/execute \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "email",
    "operation": "send_email",
    "input": {
      "to_email": "[email protected]",
      "subject": "Welcome to Acme Corp",
      "body_html": "<p>Thanks for signing up!</p>"
    },
    "domain": "acme-corp",
    "project_uuid": "8f2a1c40-..."
  }'

json

{
  "success": true,
  "service_id": "email",
  "operation": "send_email",
  "output": { "record_uuid": "9c1d...", "status": "sent" },
  "side_effects": [],
  "record_uuid": "9c1d...",
  "error": null
}

You can also send operation_id instead of operation in the execute body — both are accepted and mean the same thing.

From Python

bash

pip install supero

python

from supero.service_lib import ServiceLib

sl = ServiceLib(api_key='ak_...', domain='acme-corp', project_uuid='8f2a1c40-...')

# import + configure in one call
sl.transactional.setup(('email',), safe=False)

# typed accessor — builds the input payload and calls /services/execute for you
result = sl.email.send(
    '[email protected]',
    'Welcome to Acme Corp',
    body_html='<p>Thanks for signing up!</p>',
)

# raw escape hatch — any service_id/operation, typed accessor or not
result = sl.exec('sms', 'send_sms', {'to_number': '+15551234567', 'body': 'Your order shipped'})

From your app frontend (JavaScript)

javascript

// The same execute escape hatch documented on the Transactional Services
// page works for any catalog entry — internal or provider-backed.
await client.transactional.execute('email', 'send_email', {
  to_email: '[email protected]',
  subject: 'Welcome to Acme Corp',
  body_html: '<p>Thanks for signing up!</p>',
});

💡 Usage counts toward your plan

Calls through /services/execute count toward your plan's usage allowance the same as any other platform operation. Current plan details and prepaid credit packs are on the Billing screen in your dashboard at app.supero.dev/billing.

Checking integration health before launch

GET https://api.supero.dev/api/v1/services/preflight?domain={domain}&project_uuid={project_uuid} gives you a read-only report of every imported service in a project: whether its required config fields are present, and — for providers the platform knows how to safely probe (for example SendGrid and Twilio) — a live auth check against the provider, without ever returning the secret itself. It also validates that any workflow's bound services are imported and configured. Run it after deploying to catch a missing or revoked credential before a customer does.

Provider Config Fields & Sandbox Credentials

Each provider has its own config_data field names, set via PUT /api/v1/services/{service_id}/config. Fields marked as secret in the catalog's config_schema are stored encrypted and returned masked on read. Most providers issue free test-mode or sandbox credentials you can use during development, then swap for production keys later without changing any code — only the config values change.

service_id	Config fields to set	Getting test credentials
billing (Stripe)	stripe_api_key	A free Stripe account's test-mode secret key (sk_test_…) works instantly, no business or bank verification required. Test card: 4242 4242 4242 4242, any future expiry/CVC.
stripe_checkout	stripe_api_key, stripe_publishable_key	Same Stripe test-mode keys as above.
billing_paypal	paypal_mode, paypal_client_id, paypal_client_secret	developer.paypal.com is free and auto-creates a sandbox buyer and seller account; set paypal_mode to sandbox.
billing_razorpay	razorpay_key_id, razorpay_key_secret	A free Razorpay account's Test Mode issues rzp_test_ keys with no KYC. Test card: 4111 1111 1111 1111.
plaid	plaid_environment, plaid_client_id, plaid_secret	Plaid's free dashboard issues Sandbox keys instantly; set plaid_environment to sandbox.
sms / whatsapp (Twilio)	twilio_account_sid, twilio_auth_token	A Twilio free trial account's Test Credentials exercise the API with magic numbers — no charge, no real message sent.
email (SendGrid)	sendgrid_api_key, default_from_email, sandbox_mode	A free-tier SendGrid API key plus sandbox_mode: true validates every request and returns success without actually delivering.
email_smtp	smtp_host, smtp_username, smtp_password	A throwaway SMTP inbox provider mints test SMTP credentials for free — point smtp_host at it during development.
github	github_token, default_owner	A free GitHub account's fine-scoped personal access token, used against a throwaway repository.
okta	okta_org_url, okta_client_id, okta_client_secret, okta_api_token	A free Okta Developer org (developer.okta.com) is a real dev-*.okta.com tenant with full API access.
salesforce	salesforce_is_sandbox, salesforce_username, salesforce_password	A free Salesforce Developer Edition org; set salesforce_is_sandbox to true.
servicenow	servicenow_instance_url, servicenow_username, servicenow_password	A free ServiceNow Personal Developer Instance from developer.servicenow.com.
quickbooks	qbo_environment, qbo_client_id, qbo_refresh_token, qbo_company_id	A free Intuit developer account auto-creates a sandbox company; set qbo_environment to sandbox and mint a refresh token via Intuit's OAuth playground.
google_oauth	google_client_id, google_client_secret, redirect_uri	A free Google Cloud project's OAuth client in Testing mode — add test users, no app verification required yet.
google_calendar / google_drive	google_service_account_json	A free Google Cloud project's service-account JSON, shared onto the specific calendar or Drive folder you want to use.
push_notification (FCM)	fcm_service_account_json, fcm_project_id	A free Firebase project's service-account JSON; send to a test device token.
amazon_s3	aws_access_key_id, aws_secret_access_key, aws_region, default_bucket	An AWS Free Tier account's scoped IAM key against a throwaway bucket.
datadog	dd_api_key, dd_app_key, dd_site	A free 14-day Datadog trial issues real API and App keys instantly.

Providers That Require Business Verification

A handful of catalog providers are gated by the provider itself, not by Supero — you cannot self-serve your way to production access, and there is no free sandbox that fully substitutes for it. Build and test the rest of your integration first, and start the provider's approval process early since it can take days to weeks.

service_id	Provider	What is required before going live
instagram	Meta Graph API	A reviewed Meta app, business verification, and a linked Instagram Business account.
facebook	Meta Graph API	Meta app review, business verification, and a Page access token.
tiktok	TikTok for Developers	App review before content-posting scopes are granted.
x_social	X (Twitter) API	Write access requires a paid API tier; the free tier is read/limited.
linkedin	LinkedIn API	Posting APIs sit behind LinkedIn's Marketing/Community Partner program review.
google_ads	Google Ads API	An approved developer token and a billing-enabled Google Ads account.
google_reviews	Google Business Profile API	Allowlisted access and a verified business location.

⚠️ Plan approval lead time separately

Import and configure these the same way as any other catalog entry once you have credentials — the mechanics don't differ. The only difference is how you obtain those credentials, which is entirely on the provider's timeline.

Bring Your Own AI Provider Key

The ai entry in the catalog lets your app call OpenAI or Anthropic directly, using an API key you obtain and pay for yourself. This is separate from — and does not use — the AI Supero itself runs to generate and enhance your app; it is simply another catalog integration your app's own logic can call, the same way it might call Stripe or SendGrid.

bash

curl -X POST https://api.supero.dev/api/v1/services/import \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "ai",
    "domain": "acme-corp",
    "project_uuid": "8f2a1c40-...",
    "config_data": {
      "openai_api_key": "sk-...",
      "anthropic_api_key": "sk-ant-..."
    }
  }'

bash

curl -X POST https://api.supero.dev/api/v1/services/execute \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "ai",
    "operation": "simple_completion",
    "input": {
      "prompt": "Summarize this support ticket in one sentence.",
      "model": "<the model id for whichever provider key you configured>",
      "max_tokens": 200
    },
    "domain": "acme-corp",
    "project_uuid": "8f2a1c40-..."
  }'

From Python, the typed accessor wraps the same call:

python

result = sl.ai.complete("Summarize this support ticket in one sentence.", max_tokens=200)
# or a multi-turn call:
result = sl.ai.chat([{"role": "user", "content": "Draft a refund email."}])

ℹ️ You control the key, you control the spend

Because you supply the provider key, usage is billed by OpenAI or Anthropic directly to your own account with them — it is not metered as Supero platform usage.

How This Fits Together

There are three related but distinct pieces on the platform, and it's easy to reach for the wrong one:

If you need to…	Use
Connect a supported third-party provider (Stripe, Twilio, SendGrid, Okta, and the rest of the catalog above)	The managed services catalog documented on this page — import, configure, execute.
Model your own app's business logic — a cart, an order, a booking, an approval flow — with a real lifecycle and state machine, no external provider involved	Transactional Services — same execute primitive, no crud_object_type, no outbound call.
Wire up a provider that isn't in the catalog, or call your own internal HTTP endpoint	The Plugin Registry — register any HTTP endpoint with its own auth, retry, and circuit-breaker settings, then invoke it directly.

All three ultimately share the same reliability primitives — retries, a circuit breaker, and (for the two service-catalog paths) input validation against a declared schema — so the choice comes down to whether the provider you need is already in the catalog, not to a difference in how reliably the call is made.

Next steps

•Transactional Services — the internal ~23-service catalog (cart, order, booking, and more) that shares the same import/configure/execute lifecycle.
•Plugin Registry — the secondary, do-it-yourself path for a provider that isn't in the managed catalog or your own internal endpoint.
•Webhooks & Events — the inbound direction: a provider calling back into Supero to confirm what happened, and which providers have their signatures verified.
•Roles & Permissions Reference — who on your team can import, configure, and execute services.

← PreviousWebhooks & Events Next →Choosing a Deployment Option

On this page