B7RDevelopers
Get startedKeys and access
Get started / Keys and access

Keys and access

View .md

Every call except GET /v1/status sends a key. Keys are made in the app under Settings, then Integrations, then Custom API, by a verified account, and each one is shown once.

Send the key

  • As Authorization: Bearer <key>, or as X-B7R-Key: <key>. Send one of the two, never both.
  • Over HTTPS to https://api.b7r.app/v1. Spaces or a line break around the key are ignored.
  • Never in the query string: a URL that carries a key is refused, because URLs end up in logs.
Either header
curl https://api.b7r.app/v1/me \
  -H "Authorization: Bearer $B7R_API_KEY"

curl https://api.b7r.app/v1/me \
  -H "X-B7R-Key: $B7R_API_KEY"

What a key looks like

A key is b7r_live_ followed by 46 letters and digits, 55 characters in all. Its first 17 characters are the key prefix, shown in the app and in GET /v1/me: log the prefix to tell keys apart, never the whole key. The last 6 characters are a checksum, so a mistyped key is refused at once.

Areas

A key holds one or more areas, and each endpoint needs one. GET /v1/me works with any key.

AreaLets the keyEndpoints today
catalogRead base products and carriers, and price them.Base products, Carriers, Quote
products:readRead your products.Arrives with the products endpoints.
products:writeCreate and change your products.Arrives with the products endpoints.
orders:readRead your orders.Arrives with the orders endpoints.
orders:writeCreate and cancel orders, which charges your wallet.Arrives with the orders endpoints.
wallet:readRead the wallet balance and its movements.Arrives with the wallet endpoints.

The create screen offers presets. Website and Partner platform hold every area. AI assistant holds catalog, products:read, orders:read and wallet:read: it can read everything and change nothing. You can also pick areas one by one.

Expiry, number of keys and revoking

  • A key can carry an expiry date; after it, the key gets the same 401 as an unknown one.
  • The number of keys an account can hold is capped. The cap is an account setting.
  • Revoking a key in the app stops new calls with it at once. It cancels nothing by itself.
  • Think a key leaked? Revoke it first, then create a new one and swap it in.

The one 401

A missing, malformed, unknown, revoked or expired key all get the same answer, apart from the request_id, so a stranger learns nothing from trying keys. In the same way, another account's id answers exactly like an id that does not exist.

401 problem+json
{
  "type": "https://docs.b7r.app/errors#unauthorized",
  "title": "Invalid or missing API key",
  "status": 401,
  "code": "unauthorized",
  "retryable": false,
  "request_id": "req_7Hc2aP9xLm4Qw8Rt1Zk5Vb3N"
}

When a valid key is refused

  • 403 area_forbidden: the key lacks the endpoint's area. The error names it in valid_values.
  • 403 account_inactive: the B7R account is not active.
  • 403 connection_disabled: the Custom API is switched off for this account.
403 problem+json
{
  "type": "https://docs.b7r.app/errors#area_forbidden",
  "title": "This key cannot use this area",
  "status": 403,
  "code": "area_forbidden",
  "retryable": false,
  "request_id": "req_7Hc2aP9xLm4Qw8Rt1Zk5Vb3N",
  "errors": [
    {
      "code": "missing_area",
      "valid_values": [
        "catalog"
      ],
      "message": "The key does not have this area"
    }
  ]
}

Read your account and key

GET/v1/me

The account, the key making the call (its name, prefix, areas and expiry), the live limits, the switches and the default carrier. Call it first, and whenever you need the current limits: they are account settings and can change. The example limit is a sample.

Headers

Authorizationstringrequired

Bearer b7r_live_.... Any valid key. X-B7R-Key works too; send one, never both.

Accept-Languagestring

ar for Arabic error titles; anything else gives English. Codes never change.

Answer

accountobjectrequired
Child fields
idstring (uuid)required
store_namestringrequired
verifiedbooleanrequired
activeconstantrequired

Always true.

keyobjectrequired
Child fields
namestringrequired
prefixstringrequired
areasarray of stringrequired
expires_atstring or nullrequired
limitsobjectrequired
Child fields
calls_per_minuteintegerrequired
switchesobjectrequired
Child fields
api_enabledconstantrequired

Always true.

connection_enabledconstantrequired

Always true.

default_carrierobject or nullrequired
Child fields
idstring (uuid)required
nameobjectrequired
Child fields
arstringrequired
enstringrequired

Errors

Request
curl https://api.b7r.app/v1/me \
  -H "Authorization: Bearer $B7R_API_KEY"
const res = await fetch("https://api.b7r.app/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.B7R_API_KEY}`,
  },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://api.b7r.app/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['B7R_API_KEY']}",
    },
    timeout=30,
)
data = res.json()
200 OK
{
  "account": {
    "id": "a3f1c9e2-5b7d-4e8a-9c21-6d0f4b8e2a17",
    "store_name": "Sample Store",
    "verified": true,
    "active": true
  },
  "key": {
    "name": "Website",
    "prefix": "b7r_live_Q7m2Kx9P",
    "areas": [
      "catalog",
      "products:read",
      "products:write",
      "orders:read",
      "orders:write",
      "wallet:read"
    ],
    "expires_at": null
  },
  "limits": {
    "calls_per_minute": 120
  },
  "switches": {
    "api_enabled": true,
    "connection_enabled": true
  },
  "default_carrier": {
    "id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f",
    "name": {
      "ar": "شحن سريع",
      "en": "Express delivery"
    }
  }
}

Titles and headings of every page. llms-full.txt holds the full text.