Connect to a merchant’s account with scoped permissions

A connection is how your app gets permission to act on a specific merchant’s AskBiz data instead of your own account’s. You request it with POST /api/v1/connections, the merchant approves or narrows it on their own consent screen, and once approved you pass their ID as merchant_id on POST /api/v1/scan to read their inventory. Neither creating nor listing connections is credit-billed.

1. 1

   Request a connection to the merchant

   POST /api/v1/connections with the merchant’s email and the scopes you need. read_inventory is the only scope that exists today. This creates a pending connection and a confirmation link — nothing is granted yet.

   cURLJavaScriptPython

   curl -X POST https://askbiz.co/api/v1/connections \
     -H "x-api-key: abz_live_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_email": "owner@example-shop.com",
       "scopes": ["read_inventory"]
     }'

2. 2

   Send the merchant their confirmation link

   The response includes confirmation_url — a link to https://developer.askbiz.co/connect/{token} that’s valid for 7 days (see expires_at). Send it to the merchant however you already reach them: email, WhatsApp, SMS. There’s no in-band way to deliver it; that’s on you.

   200 — connection created

   {
     "connection": {
       "id": "c1a2b3c4-...",
       "merchant_email": "owner@example-shop.com",
       "status": "pending",
       "scopes": ["read_inventory"],
       "created_at": "2026-07-17T09:00:00Z",
       "expires_at": "2026-07-24T09:00:00Z"
     },
     "confirmation_url": "https://developer.askbiz.co/connect/8f2e1a9c-4b3d-4e5f-9a0b-1c2d3e4f5a6b"
   }

3. 3

   The merchant reviews and approves on a real consent screen

   They open the link, sign in to their own AskBiz account, and see exactly the scopes you requested — nothing vague, nothing bundled. They can untick any scope before approving (narrowing only, never granting more than you asked for), or decline entirely. This step happens entirely on their side — you don’t call anything for it.

4. 4

   Check GET /api/v1/connections for status: "approved"

   There’s no webhook for connection status changes (webhooks only cover sale.created, purchase_order.received, and stock.low), so poll GET /api/v1/connections and match on merchant_email. Once status is "approved", the connection carries a merchant_user_id and the final scopes array — check scopes too, since the merchant may have approved fewer than you requested.

   cURLJavaScriptPython

   curl https://askbiz.co/api/v1/connections \
     -H "x-api-key: abz_live_your_key_here"

   An approved connection looks like this:

   200 — approved

   {
     "connections": [
       {
         "id": "c1a2b3c4-...",
         "merchant_email": "owner@example-shop.com",
         "merchant_user_id": "u7d8e9f0-...",
         "status": "approved",
         "scopes": ["read_inventory"],
         "created_at": "2026-07-17T09:00:00Z",
         "approved_at": "2026-07-17T09:14:00Z",
         "revoked_at": null
       }
     ]
   }

5. 5

   Use merchant_id on POST /api/v1/scan

   Pass the connection’s merchant_user_id as merchant_id on a scan call. With an approved read_inventory connection, the scan is matched against that merchant’s live inventory instead of your own account’s — same endpoint, same pricing, same Idempotency-Key contract.

   cURLJavaScriptPython

   curl -X POST https://askbiz.co/api/v1/scan \
     -H "x-api-key: abz_live_your_key_here" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 5a9e2c1e-6b3f-4a2d-9c11-3f7e8a0b1c2d" \
     -d '{
       "image": "<base64-encoded JPEG>",
       "merchant_id": "u7d8e9f0-..."
     }'

Why scoped consent matters

This is the closest thing to an OAuth permission dialog in the AskBiz product, and it’s worth building your integration around the same assumptions you’d bring to any OAuth flow:

• You never get silent or implicit access — a connection stays pending until the merchant explicitly acts on it.
• The merchant sees exactly what you asked for. There’s no bundling scopes together or hiding one behind another.
• Approval can only narrow your request, never widen it — if you ask for read_inventory, the merchant can grant that or nothing, never more than you requested.
• Revocation is merchant-initiated only. They can revoke an approved connection from their own confirmation page at any time; there’s no developer-initiated revoke endpoint today. Design your integration to handle a connection disappearing without warning — re-check status rather than assuming a past approval still holds.
• If you already have an active connection to a given merchant_email, a second POST returns 409 instead of creating a duplicate — reuse the existing one via GET rather than retrying blindly.

What’s next

Full parameter-by-parameter detail — including the scopes default behavior and every error code — is in the connections API reference. For everything else the scan call can return once you’re connected, see the scan API reference.