Connect flow for plugins: /connect

How it works

Your plugin opens https://app.my-store-locator.com/connect with the parameters platform, return_url and state.
The user signs in or registers. The request is kept for 60 minutes along the way - also through two-factor sign-in, the e-mail sign-in link and e-mail confirmation.
The app shows "Connect WordPress with My Store Locator" (with the name of your platform) and the address it will return to: "You will be sent back to shop.example.com".
The user picks a map. Users without a map create their first one right there.
After Connect the browser goes back to your return_url with msl_token, msl_map and state added.

No secret is exchanged: map tokens are public, they are part of every embed code. The flow works on every plan, including the free one.

The request

https://app.my-store-locator.com/connect?platform=wordpress&return_url=https%3A%2F%2Fshop.example.com%2Fwp-admin%2Fadmin.php%3Fpage%3Dmsl&state=4f9c2a7e1b8d4c6f

Parameter	Required	Rules
`platform`	yes	one of the platforms below
`return_url`	yes	absolute address with `https://` (for development also `http://localhost`, `http://127.0.0.1`, `http://[::1]`), at most 2048 characters, no `user:password@`, no spaces, control characters or backslash. Pass it URL-encoded
`state`	recommended	1 to 200 characters from `A-Z a-z 0-9 . _ ~ -`. Returned unchanged
`lang`	no	`de` or `en` for the page language

Allowed values for platform: wordpress, woocommerce, shopify, shopware, typo3, joomla, drupal, wix, webflow, framer, zapier, n8n, make, and other for everything else. Your platform is missing? Use other and get in touch.

The return

https://shop.example.com/wp-admin/admin.php?page=msl&msl_token=a1b2c3d4e5f6a7b8&msl_map=Stores&state=4f9c2a7e1b8d4c6f

Parameter	Content
`msl_token`	token of the chosen map - exactly the value for `data-token`
`msl_map`	name of the map (at most 200 characters), e.g. to show it in your plugin
`state`	your value from the request; missing if you did not send one

Existing query parameters and a fragment of your return_url are kept. Only msl_token, msl_map and state are set or replaced.

What your plugin should check

state: create a random value before the request, keep it in the session and compare it on return. This way you notice returns your plugin did not start itself.
Token: check msl_token against ^[A-Za-z0-9_-]{6,64}$ before you store it.
Permission: store the token only if the signed-in user may change this setting in your system.

Example in PHP:

// 1. "Connect to My Store Locator" button
$state = bin2hex(random_bytes(16));
$_SESSION['msl_state'] = $state;
$url = 'https://app.my-store-locator.com/connect?' . http_build_query([
    'platform'   => 'wordpress',
    'return_url' => 'https://shop.example.com/wp-admin/admin.php?page=msl',
    'state'      => $state,
]);

// 2. Return to return_url
$expected = $_SESSION['msl_state'] ?? '';
unset($_SESSION['msl_state']);
if ($expected === '' || !hash_equals($expected, (string) ($_GET['state'] ?? ''))) {
    exit('Invalid request');
}
$token = (string) ($_GET['msl_token'] ?? '');
if (!preg_match('/^[A-Za-z0-9_-]{6,64}$/', $token)) {
    exit('Invalid token');
}
// store $token, show $_GET['msl_map'] as the map name

Errors and cancelling

Invalid requests never redirect. The app shows an error page instead, for example "The return address must start with https://."

You can check your parameters beforehand - without signing in:

curl -H "X-MSL-Lang: en" "https://app.my-store-locator.com/api/v1/connect/check?platform=wordpress&return_url=https%3A%2F%2Fshop.example.com%2Fcb&state=abc123"

{ "ok": true, "platform": "wordpress", "name": "WordPress", "host": "shop.example.com" }

Errors return HTTP 400 with error = bad_platform, bad_state or bad_return_url. For bad_return_url, data.reason gives the reason: missing, scheme, too_long or invalid.

If the user cancels, they end up in the app dashboard - there is no return to your plugin. So keep offering the button, plus a field where users can paste the token or the embed code (see reading the token from user input).

Good to know

The signed-in user needs permission to view maps. Connecting is not possible in the demo account.
Drafts can be picked too. The map is publicly visible only once it is published in the app. A map created inside the connect flow is published right away if the user has the right to publish - with no locations at first.
Every connection is written to the account's audit log ("Plattform verbunden", with map and target host).
New accounts created through the flow remember your platform as their sign-up source.

Links from your plugin

When your plugin links to our website or to the sign-up, please add campaign parameters:

https://app.my-store-locator.com/#/register?utm_source=wordpress
https://my-store-locator.com/en/?utm_source=wordpress&utm_medium=integration&utm_campaign=wordpress-plugin

For your plugin's privacy notes: the map is served from app.my-store-locator.com (hosted in Germany). When the map loads, the visitor's IP address is transferred to our server. Our privacy policy is at /en/privacy/.