Keys and access
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 asX-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.
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.
| Area | Lets the key | Endpoints today |
|---|---|---|
catalog | Read base products and carriers, and price them. | Base products, Carriers, Quote |
products:read | Read your products. | Arrives with the products endpoints. |
products:write | Create and change your products. | Arrives with the products endpoints. |
orders:read | Read your orders. | Arrives with the orders endpoints. |
orders:write | Create and cancel orders, which charges your wallet. | Arrives with the orders endpoints. |
wallet:read | Read 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
401as 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.
{
"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 invalid_values.403 account_inactive: the B7R account is not active.403 connection_disabled: the Custom API is switched off for this account.
{
"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
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
Bearer b7r_live_.... Any valid key. X-B7R-Key works too; send one, never both.
ar for Arabic error titles; anything else gives English. Codes never change.
Answer
Child fields
Always true.
Child fields
Child fields
Child fields
Always true.
Always true.
Child fields
Child fields
Errors
| HTTP | Code | Retry |
|---|---|---|
| 401 | unauthorized | No |
| 403 | account_inactive | No |
| 403 | connection_disabled | No |
| 400 | invalid_request | No |
| 429 | rate_limited | Yes |
| 500 | internal_error | Yes |
| 502 | upstream_unavailable | Yes |
| 503 | api_unavailable | Yes |
| 503 | request_expired | Yes |
| 503 | service_unavailable | Yes |
| 504 | upstream_timeout | Yes |
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(){
"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"
}
}
}