# Admin API — Python Client Usage

**The canonical HTTP reference for every admin-api endpoint is the OpenAPI spec at [`../../docs/openapi/admin-api.yaml`](../../docs/openapi/admin-api.yaml).** Read it interactively at <http://localhost:8000/scalar/admin.html> (run `yarn docs:serve` from the repo root). The Scalar page documents method, path, auth, parameters, request/response shapes, and error codes for all 273 endpoints. Start there for any "what does endpoint X return?" question.

This file covers only the Python-specific bits: how to call those endpoints from [`api.py`](./api.py).

## Setup

`api.py` reads connection details and credentials from a `.env` file:

```env
BIGSCREEN_API_URL=https://api.bigscreenvr.com
BIGSCREEN_ADMIN_API_URL=https://admin-api.bigscreenvr.com
BIGSCREEN_CLOUD_API_URL=https://cloud-api.bigscreenvr.com
BIGSCREEN_API_KEY=<admin-api key>
ADMIN_ACCOUNT_EMAIL=<your @bigscreenvr.com email>
ADMIN_ACCOUNT_PASSWORD=<account password>
```

The account referenced by `ADMIN_ACCOUNT_EMAIL` must have the access policies required by the endpoints you're calling (see the OpenAPI spec's `components.securitySchemes` block and each endpoint's `x-access-policies` extension for the policy list).

## Authenticating

```python
from api import BigApi

BigApi.init("./.env")
BigApi.login(BigApi.adminEmail, BigApi.adminPassword)
# BigApi.accessToken is now populated.
```

`BigApi.login(...)` hits the public auth server (`BIGSCREEN_API_URL/login`) and stores the returned access token on the class.

## Calling an admin endpoint

Every `/admin/*` request needs the two headers supplied by `BigApi.getAdminHeaders()`:

| Header | Value |
|--------|-------|
| `Authorization` | `Bearer <BIGSCREEN_API_KEY>` |
| `x-access-token` | The JWT from `BigApi.login(...)` |

Example — query an account by email (see [../../docs/services/admin-api/moderation.md](../../docs/services/admin-api/moderation.md#get-adminaccountqueryfieldvalue)):

```python
import requests
from api import BigApi

BigApi.init("./.env")
BigApi.login(BigApi.adminEmail, BigApi.adminPassword)

email = "someone@example.com"
response = requests.get(
    f"{BigApi.adminApiUrl}/admin/account/query/email/{email}",
    headers=BigApi.getAdminHeaders(),
)
response.raise_for_status()
account = response.json()
print(account["username"], account["id"])
```

## Common pitfalls

- **`401 Unauthorized`** — access token is missing, expired, or the wrong account is logged in. Re-run `BigApi.login(...)`.
- **`403 Forbidden`** — authenticated successfully but the account lacks the required access policy. Check the endpoint's `**Auth:**` line in its module doc.
- **Factory / non-admin endpoints** — `/fusion/*`, `/cnc/*`, `/pose/*` use *different* API keys (`FUSION_API_KEY`, `CNC_MACHINE_API_KEY`, `POSE_API_KEY`). `BigApi.getAdminHeaders()` is only valid for `/admin/*` routes.
- **5xx from mutating endpoints** — usually means the handler threw. Check the admin-api process logs; the docs only list 4xx codes that handlers explicitly emit.

## See also

- [../../docs/services/admin-api/README.md](../../docs/services/admin-api/README.md) — full endpoint reference (index)
- [../../docs/services/admin-api/authentication.md](../../docs/services/admin-api/authentication.md) — policies, scopes, bearer types
- [../../docs/services/admin-api/\_endpoints.md](../../docs/services/admin-api/_endpoints.md) — generated quick-search table of every documented endpoint
- [../../docs/services/admin-api/\_test-coverage.md](../../docs/services/admin-api/_test-coverage.md) — which integration tests cover which endpoint (use this to find worked request/response examples)
- [`api.py`](./api.py) — the Python client source