# Authentication

Kailangan ng API key sa bawat tawag na nagpapatakbo ng modelo o nagbabasa ng iyong mga kahilingan. Pampubliko ang catalog (`GET /models`,
`GET /categories`), `POST /quote` at ang OpenAPI document.

## Mga API key

Gumawa at mag-revoke ng mga key sa [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ang key ay mukhang
`doitong_` na sinusundan ng 64 hex character at isang beses lang ipinapakita kapag ginawa mo ito. Ipadala ito sa
`Authorization` header:

```bash
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

Gumagana rin ang `X-API-Key: <key>`.

> [!WARNING]
> Itago ang mga key sa iyong server: maaaring gastusin ng sinumang may key ang kredito ng API na pinahihintulutang gastusin nito. Kung may tumagas na key,
> i-revoke ito at gumawa ng bago.

Ang kahilingang walang key ay makakakuha ng `401` na may code na `missing_api_key`; makakakuha rin ng `401` ang hindi kilala, na-revoke o nag-expire na key.

## Mga saklaw

May mga scope ang bawat key. Sinusuri ng modelo API ang mga ito:

| Aksyon | Kailangan na scope |
|---|---|
| Magpatakbo ng modelo, magkansela ng kahilingan, mag-delete ng mga file ng kahilingan, magpalit ng setting ng storage | `models:run` (gumagana rin ang mga key na may mas lumang `images:create` o `videos:create`) |
| Gumawa ng upload URL | `models:run` o `media:upload` |
| Magbasa ng mga kahilingan, account | `models:read` (nakakabasa rin ng mga modelo ang key na maaaring magpatakbo ng mga ito) |

Awtomatikong nakakakuha ang mga bagong key ng `models:read` at `models:run`. Ang tawag na walang tamang scope ay makakakuha ng `403` na may code na
`insufficient_scope`.

## Mga badyet sa kredito

Maaaring magkaroon ang isang key ng sariling badyet sa kredito ng API (1,000 kredito ng API = $1), na itinatakda ng may-ari ng account: kabuuang badyet, pang-araw-araw na badyet (nakaraang 24 na oras), o pareho. Bago singilin ang isang pagtakbo, sinusuri ang gastos laban sa nagastos na ng key sa API na ito (matapos ibawas ang mga refund). Ang pagtakbong lalampas dito ay tatanggihan na may `402 budget_exceeded` at walang sisingilin.

> [!IMPORTANT]
> Pangwakas ang pagtanggi dahil sa badyet: walang maitutulong ang pag-retry hanggang taasan ng may-ari ang badyet.

 Ang key na walang badyet ay maaaring gumastos nang hanggang sa balanse ng API. Hiwalay dito, ang pagtakbong hindi kayang sagutin ng balanse ng API ay makakakuha ng `402 insufficient_credits`
na may `top_up_url`.

Ipinapakita ng `GET https://api.doitong.com/v1/account` ang balanse ng API at natitirang badyet ng key (parehong nasa kredito ng API):

```json 200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}
```

Ang `budget_remaining` ay `null` kapag walang sariling badyet ang key.

## Mga limitasyon sa rate

Maaaring gumawa ang bawat key ng 3600 kahilingan bawat oras maliban kung iba ang itinakdang limitasyon nito. Taglay ng bawat authenticated response ang kasalukuyang estado:

| Header | Kahulugan |
|---|---|
| `X-RateLimit-Limit` | Mga kahilingang pinapayagan sa kasalukuyang window |
| `X-RateLimit-Remaining` | Mga natitirang kahilingan sa kasalukuyang window |
| `X-RateLimit-Reset` | Unix time kung kailan magre-reset ang window |

Kapag lumampas sa limitasyon, makakakuha ka ng `429` na may `Retry-After` header (segundo). Ang long polling na may `?wait=` ay binibilang na isang kahilingan bawat tawag, kaya mas matipid ang paghihintay kaysa mabilis na polling.

May limitasyon din na 10 kahilingang isinasagawa (`queued` o `running`) bawat account. Ang pagsisimula ng isa pa ay nagbabalik ng
`429 too_many_inflight`; simulan itong muli pagkatapos matapos ang isa.