The connect flow lets a merchant on Ewity link their platform account to your service in a self-serve way — no human-in-the-loop on Ewity's side. It avoids a full OAuth dance: the merchant clicks Connect on Ewity, follows your instructions to generate a one-shot pairing code in your dashboard, pastes it into Ewity, and Ewity calls back to your service to verify and consume the code.
New to the connect flow? Start with the step-by-step guide —
Implementing the Ewity Connect Flow — which
walks the whole merchant journey screen by screen, with mockups of both your
dashboard and the Ewity UI. This page and its two children are the exact
endpoint contracts.
URLs you configure
Set these on your application's Configuration tab in the
Developer Portal:
| URL | Purpose |
|---|---|
| Connect URL | The single endpoint Ewity hits for both the connect-info GET and the code-verification POST described below. |
| Webhook URL | Where we POST order/store/review events to you. See the Webhooks section. |
| Inventory webhook URL (optional) | Where we POST CatalogueUpdated events when a merchant changes stock or catalogue membership. Skip this if you don't track inventory on your side. See CatalogueUpdated. |
The shared bearer token used for both directions is your application's API key (Credentials tab). There is no public client/secret you need to host.
End-to-end flow
- Merchant goes to Ewity → Ecommerce Platforms → clicks Connect on your platform → modal opens.
- Ewity calls
GET {connect_url}. You respond with onboarding instructions — "to generate a connection code, log in to your platform dashboard, open Settings → Integrations → Ewity, click Generate Connection Code, and paste it back here." Ewity renders these instructions in the modal so the merchant knows what to do next. - Merchant follows your instructions on your platform — logs in, navigates to wherever your dashboard exposes the integration, and clicks the Generate Connection Code button you've built. You mint a one-shot code there: a short string (~12+ chars), bound to that merchant's account on your side, with a short TTL (~10 minutes recommended) and single-use semantics. Show the code on screen for them to copy.
- Merchant returns to the still-open Ewity modal, pastes the code, clicks Submit.
- Ewity calls
POST {connect_url}with{connect_code}. You verify the code, mark it consumed, and return the merchant's identifier on your side asexternal_account_id. - Ewity links the merchant to your platform. From this point on, the merchant's
platform-v1calls (orders, payments, etc.) are scoped to that link.
The merchant never has to "find" your platform on their own — the GET response is your chance to walk them through whatever steps your product needs. If your code-generation UI lives behind several clicks, your instructions text is what tells them how to get there.
Why a code instead of OAuth
The merchant authenticates on your side before generating the code — so a code only ever exists for the rightful owner of an account. That gives us the same trust property as OAuth ("the merchant is connecting their account") without you having to host a client/secret table, redirect URIs, or refresh-token rotation.
Auth on every request
Both GET and POST to your connect URL include Authorization: Bearer {your_shared_platform_auth_token} — the same token you already use to authenticate inbound platform-v1 calls. Verify it on every request. Reject anything else with 401.
Disconnect
A merchant can disconnect from your platform at any time from the Ecommerce Platforms page. We currently do not call back to your platform on disconnect — if you need notification, let us know and we'll add a revoke webhook.