Docs / Getting started
Authentication
API keys, the Authorization header, and what a key can do.
Reading the catalog needs no key. A key gets you photos, contributing, and a higher rate limit:
GET /v1/items?q=catan
Authorization: Bearer bgdb_…| Without a key | With a key | |
|---|---|---|
| Items, search, lookup, credits, terms, history | yes | yes |
| Photo links | first page of a list only | yes |
| Submissions and uploads | no | yes |
| Requests per minute | 120 per address | 600 (user) or 6,000 (bot) |
Keys
Make keys in the web app under Account → API keys. Each key is shown once, has a label so you know what it is for, and can be revoked there. A key never expires on its own.
Treat a key like a password: keep it in an environment variable or a secret store, not in client-side code. If a key leaks, revoke it and make another.
What a key can do
| With a key you can | Not with a key |
|---|---|
| Read everything | Create accounts, log in, or reset passwords |
| Submit new items and changes (see Submissions) | Review or approve anything |
| Upload photos | Make or revoke keys |
See your own submissions and GET /v1/me | Admin functions |
Accounts and administration happen only in the web app. An admin's API key acts like any user's key: its submissions wait for review.
Roles
| Role | Submissions | Rate limit |
|---|---|---|
| user | Reviewed by an admin before publishing | 600 requests/minute |
| bot | Published at once, unless flagged as a possible duplicate | 6,000 requests/minute |
Bot keys are given to scrapers and trusted integrations. Ask if you need one.