# Keys

The keyed products need a key. Sign in with Roblox, make one, keep it on the server, send it as a bearer.

## Getting a key

Sign in with your Roblox account at [api.dietbloxycola.com/account](https://api.dietbloxycola.com/docs/https://api.dietbloxycola.com/account). The first sign-in makes an account that waits for approval; once it is approved, the keys page makes live and test keys, shows each secret once, and revokes them. A key belongs to the account, not to a game: one key may read any universe.

- An account holds at most 5 live keys, so rotating is making the next one, moving your game to it, and revoking the old one.
- A key is issued with scopes, one per product it may use; an endpoint's page names the scope it needs.
- A revoked key stops within 30 seconds everywhere, and at once on the node that revoked it.
- A test key is the same credential with two differences: whatever it writes lands in the test era, and it spends against a 10th of the live limits.

## Sending it

Every keyed request carries `Authorization: Bearer <key>`. Keep the key on the server: in a Roblox game, as a Creator Hub secret named `dbc_api_key` scoped to `api.dietbloxycola.com`, read with `HttpService:GetSecret`, so the script never holds its text. Keyed endpoints send no CORS headers, so a browser cannot call them; that is on purpose.

cURL:

```bash
curl https://api.dietbloxycola.com/v1/account \
  -H "Authorization: Bearer $DBC_API_KEY"
```
JavaScript:

```js
const res = await fetch("https://api.dietbloxycola.com/v1/account", {
  headers: {
    Authorization: `Bearer ${process.env.DBC_API_KEY}`,
  },
});
const account = await res.json();
```
Python:

```python
import requests
import os

account = requests.get("https://api.dietbloxycola.com/v1/account", headers={"Authorization": f"Bearer {os.environ['DBC_API_KEY']}"}, timeout=10).json()
```
Luau:

```lua
-- HttpService must be on in the game's settings. The key is a Creator Hub
-- secret named dbc_api_key, scoped to api.dietbloxycola.com; the script never
-- sees its text.
local HttpService = game:GetService("HttpService")

local response = HttpService:RequestAsync({
  Url = "https://api.dietbloxycola.com/v1/account",
  Method = "GET",
  Headers = {
    Authorization = HttpService:GetSecret("dbc_api_key"):AddPrefix("Bearer "),
  },
})
local account = HttpService:JSONDecode(response.Body)
```

## The shape

`dbc_live_` or `dbc_test_` and 32 characters of letters and digits. The first four characters after the mode are the prefix the portal and the account endpoint show, so a key can be told apart without being shown.

HTTP:

```http
Authorization: Bearer dbc_live_ab12CdEf34GhIj56KlMn78OpQr90StUv
```

## What a refusal means

A bad, revoked or expired key is `unauthorized`; a real key without the endpoint's scope is `insufficient_scope`; an account not yet approved is `tenant_pending`; a suspended one is `tenant_suspended`; a product switched off is `product_disabled`. The checks run in that order, before any budget is spent, and the [errors](https://api.dietbloxycola.com/docs/errors) page has the whole table. Ten failed authentications a minute from one address block that address for five minutes; a good key does not lift the block, so a fleet of servers behind one address should not retry a dead key in a loop.