# Autentisering

Ethvert kall som kjører en modell eller leser forespørslene dine, trenger en API-nøkkel. Katalogen (`GET /models`,
`GET /categories`), `POST /quote` og OpenAPI-dokumentet er offentlige.

## API-nøkler

Opprett og tilbakekall nøkler på [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). En nøkkel ser ut
som `doitong_` etterfulgt av 64 heksadesimale tegn, og vises bare én gang når du oppretter den. Send den i
`Authorization`-headeren:

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

`X-API-Key: <key>` fungerer også.

> [!WARNING]
> Oppbevar nøkler på serveren: alle som har en nøkkel, kan bruke API-kredittene den har tillatelse til å bruke. Hvis en nøkkel lekker,
> tilbakekaller du den og oppretter en ny.

En forespørsel uten nøkkel får `401` med koden `missing_api_key`; en ukjent, tilbakekalt eller utløpt nøkkel får også `401`.

## Omfang

Hver nøkkel har scopes. Modell-API-et kontrollerer disse:

| Handling | Nødvendig scope |
|---|---|
| Kjør en modell, avbryt en forespørsel, slett en forespørsels filer, endre lagringsinnstillingen | `models:run` (nøkler med de eldre `images:create` eller `videos:create` fungerer også) |
| Opprett en opplastings-URL | `models:run` eller `media:upload` |
| Les forespørsler, konto | `models:read` (en nøkkel som kan kjøre modeller, kan også lese) |

Nye nøkler får `models:read` og `models:run` som standard. Et kall uten riktig scope får `403` med koden
`insufficient_scope`.

## Kredittbudsjetter

En nøkkel kan ha sitt eget budsjett i API-kreditter (1 000 API-kreditter = 1 $), angitt av kontoeieren: et totalbudsjett, et
daglig budsjett (siste 24 timer), eller begge deler. Før en kjøring belastes, kontrolleres kostnaden mot det nøkkelen allerede har
brukt gjennom dette API-et (etter tilbakebetalinger). En kjøring som ville overskride grensen, avvises med `402 budget_exceeded`, og ingenting
belastes.

> [!IMPORTANT]
> En budsjettavvisning er endelig: det hjelper ikke å prøve på nytt før eieren øker budsjettet.

 En nøkkel uten budsjett kan
bruke opptil API-saldoen. Separat blir en kjøring som API-saldoen ikke kan dekke, avvist med `402 insufficient_credits`
med en `top_up_url`.

`GET https://api.doitong.ru/v1/account` viser API-saldoen og nøkkelens gjenværende budsjett (begge i API-kreditter):

```json 200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/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_..."
}
```

`budget_remaining` er `null` når nøkkelen ikke har eget budsjett.

## Fartsgrenser

Hver nøkkel kan gjøre 3600 forespørsler per time, med mindre grensen er satt annerledes. Alle autentiserte svar inneholder
gjeldende status:

| Header | Betydning |
|---|---|
| `X-RateLimit-Limit` | Antall forespørsler som er tillatt i det gjeldende vinduet |
| `X-RateLimit-Remaining` | Gjenstående forespørsler i det gjeldende vinduet |
| `X-RateLimit-Reset` | Unix-tidspunktet når vinduet tilbakestilles |

Når grensen overskrides, får du `429` med en `Retry-After`-header (sekunder). Lang polling med `?wait=` teller som én forespørsel
per kall, så det er billigere å vente enn å polle raskt.

Det finnes også en grense på 10 pågående forespørsler (`queued` eller `running`) per konto. Hvis du starter én til, returneres
`429 too_many_inflight`; start den på nytt etter at én er ferdig.