POST + GET /api/v1/connections

What it does

A connection is how your app gets permission to act on a specific AskBiz merchant’s data instead of your own. You POST a merchant’s email and the scopes you want; AskBiz creates a pending connection and hands you back a confirmation link. The merchant opens that link, signs in, and approves or declines on their own consent screen — nothing is granted until they do. GET lists the connections your key has created, so you can poll for status instead of guessing when a merchant acts.

Neither POST nor GET on this endpoint is credit-billed. The only scope that exists today is read_inventory, which — once approved — lets your key pass that merchant’s user ID as merchant_id on POST /api/v1/scan to read their inventory instead of your own.

On a test key (abz_test_…), POST never reaches a real merchant — it returns an already-active fixture connection instantly instead, with merchant_email fixed to a sandbox address regardless of what you send, and connection.test_mode: true in the response. No email is sent and no real AskBiz account is touched. See Build safely with a sandbox key.

Request

POST — create a connection

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"]
  }'

GET — list your connections

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

No parameters. Returns every connection your key has created, most recent 200.

Scopes

A scope is a single, named permission a connection can grant. The only scope that exists today is read_inventory, which lets your key read the connected merchant’s inventory via merchant_id on POST /api/v1/scan. There is no scope yet for writing data, reading sales, or anything beyond inventory — don’t request or expect one.

If you omit scopes on the POST body, AskBiz requests the full current set on your behalf (today that’s still just read_inventory). As more scopes are added in the future, this default will only ever apply to integrations that predate scopes — always pass scopes explicitly in new code so you request exactly what you need.

The merchant consent screen

This works the same way OAuth-style permission dialogs do on other platforms: you ask for a specific set of permissions, and the merchant sees and controls exactly what they’re granting — you never get silent or implicit access.

• Your POST creates a pending connection and a confirmation link at https://developer.askbiz.co/connect/{token}, valid for 7 days (reflected in expires_at).
• The merchant opens the link and signs in to their own AskBiz account.
• They see a real consent screen listing exactly the scopes you requested — nothing vague, no bundled permissions.
• They can untick any scope before approving. This is narrowing only: they can grant less than you asked for, never more than you requested.
• They can decline entirely, leaving the connection unapproved.
• Once approved, read_inventory connections let you pass that merchant’s ID as merchant_id on POST /api/v1/scan.

Revocation is merchant-initiated only — they can revoke an approved connection from their own confirmation page at any time. There is no developer-initiated revoke endpoint today; if a merchant needs to be disconnected, ask them to revoke it from their side.

Response

POST — 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"
}

GET — 200, most recent 200 connections:

{
  "connections": [
    {
      "id": "c1a2b3c4-...",
      "merchant_email": "owner@example-shop.com",
      "merchant_user_id": "u7d8e9f0-...",
      "status": "approved",
      "scopes": ["read_inventory"],
      "created_at": "2026-07-10T09:00:00Z",
      "approved_at": "2026-07-10T09:12:00Z",
      "revoked_at": null
    },
    {
      "id": "d2b3c4d5-...",
      "merchant_email": "another-shop@example.com",
      "merchant_user_id": null,
      "status": "pending",
      "scopes": ["read_inventory"],
      "created_at": "2026-07-16T14:30:00Z",
      "approved_at": null,
      "revoked_at": null
    }
  ]
}

Errors