# Autentificaziun

Mintga clamada che exequescha in model u legia tias dumondas dovra ina clav API. Il catalog (`GET /models`, `GET /categories`), `POST /quote` e il document OpenAPI èn publics.

## Clavs API

Crees e revoches clavs a [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ina clav sumeglia `doitong_` suandà da 64 caracters hexadecimals e vegn mussada mo ina giada, cura che ti la creeschas. Trametta ella en il header `Authorization`:

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

`X-API-Key: <key>` funcziuna medemamain.

> [!WARNING]
> Tegna las clavs sin tes server: mintga persuna che posseda ina clav po spendrar ils credits API ch'ella ha il dretg da spendrar. Sche ina clav vegn enconuschenta, revochescha ella e crees ina nova.

Ina dumonda senza clav survegn `401` cun il code `missing_api_key`; ina clav nunenconuschenta, revocada u scadida survegn medemamain `401`.

## Scopes

Mintga clav porta scopes. L'API dals models controlla quels:

| Action | Scope needed |
|---|---|
| Exequir in model, cancellar ina dumonda, stizzar las datotecas d'ina dumonda, midar la configuraziun da memorisaziun | `models:run` (clavs cun l'anteriur `images:create` u `videos:create` funcziunan era) |
| Crear ina URL d'upload | `models:run` u `media:upload` |
| Leger dumondas, conto | `models:read` (ina clav che po exequir models po era leger) |

N novas clavs survegnan `models:read` e `models:run` sco standard. Ina clamada senza il scope adequat survegn `403` cun il code `insufficient_scope`.

## Budgets da credits

Ina clav po avair ses agen budget en credits API (1 000 credits API = $1), fixà dal proprietari dal conto: in budget total, in budget quotidian (las ultimas 24 uras), u omadus. Avant che ina execuziun vegn chargiada, vegn il cust controllà cunter quai che la clav ha gia spendì tras questa API (net da las restitaziuns). Ina execuziun che surpassass il budget vegn refusada cun `402 budget_exceeded` e nagut vegn chargià.

> [!IMPORTANT]
> Ina refusaziun per budget è definitiva: ina repetiziun na gida betg fin che il proprietari augmenta il budget.

 Ina clav senza budget po spendrar fin al saldo API. Separadamain, ina execuziun che il saldo API na po betg cuvrir survegn `402 insufficient_credits` cun in `top_up_url`.

`GET https://api.doitong.com/v1/account` mussa il saldo API e il budget restant da la clav (omadus en credits API):

```json 200 OK · conto
{
  "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_..."
}
```

`budget_remaining` è `null` cura che la clav n'ha betg in agen budget.

## Limits da frequenza

Mintga clav po far 3600 dumondas per ura, nun ch'il limit saja vegnì definì autramain. Mintga resposta autentifitgada cuntegna il stadi actual:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Dumondas permessas en la fanestra actuala |
| `X-RateLimit-Remaining` | Dumondas restantas en la fanestra actuala |
| `X-RateLimit-Reset` | Temp Unix cura che la fanestra vegn reaviarta |

Sur il limit survegns `429` cun in header `Retry-After` (secundas). Il polling lung cun `?wait=` quinta sco ina dumonda per clamada, uschia che l'attesa è pli favuraivla che far polling svelt.

I dat era in limit da 10 dumondas en execuziun (`queued` u `running`) per conto. Lantschar ina ulteriura returna `429 too_many_inflight`; lantscha ella danovamain suenter che ina è terminada.