# Keys and access

> How to send a key, what its areas allow, the presets, expiry and revoking, and the one answer every bad key gets.

Source: https://docs.b7r.app/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 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:

```bash
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](https://docs.b7r.app/catalog), [Carriers](https://docs.b7r.app/carriers), [Quote](https://docs.b7r.app/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 `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:

```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:

```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.

Key: Any valid key.

Answer:

- `account` (object, required)
  - `id` (string (uuid), required)
  - `store_name` (string, required)
  - `verified` (boolean, required)
  - `active` (constant, required): Always `true`.
- `key` (object, required)
  - `name` (string, required)
  - `prefix` (string, required)
  - `areas` (array of string, required)
  - `expires_at` (string or null, required)
- `limits` (object, required)
  - `calls_per_minute` (integer, required)
- `switches` (object, required)
  - `api_enabled` (constant, required): Always `true`.
  - `connection_enabled` (constant, required): Always `true`.
- `default_carrier` (object or null, required)
  - `id` (string (uuid), required)
  - `name` (object, required)
    - `ar` (string, required)
    - `en` (string, required)

Errors: `unauthorized` (401), `account_inactive` (403), `connection_disabled` (403), `invalid_request` (400), `rate_limited` (429), `internal_error` (500), `upstream_unavailable` (502), `api_unavailable` (503), `request_expired` (503), `service_unavailable` (503), `upstream_timeout` (504). See [Errors](https://docs.b7r.app/errors).

Request:

```bash
curl https://api.b7r.app/v1/me \
  -H "Authorization: Bearer $B7R_API_KEY"
```

```javascript
const res = await fetch("https://api.b7r.app/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.B7R_API_KEY}`,
  },
});
const data = await res.json();
```

```python
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()
```

Answer (200 OK):

```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"
    }
  }
}
```
