Kom i gang

Autentisering og API-nøkler

Nøkkeltyper og prefikser, hvor du oppretter dem, tilganger, forespørselsgrenser, rotasjon og hva hver autentiseringsfeil betyr.

Sende nøkkelen

Authorization: Bearer sk_stav_live_...

x-api-key: sk_stav_live_... fungerer også, fordi det er slik Anthropic SDK sender nøkkelen sin. Hvis begge headerne er til stede, vinner Authorization.

Base URL for alle flater: https://api.stav.ai/v1.

Nøkkeltyper

Prefiks	Type	Miljø
`sk_stav_live_`	Arbeidsområdenøkkel	Produksjon
`sk_stav_test_`	Arbeidsområdenøkkel	Test
`sk_stav_user_live_`	Personlig nøkkel	Produksjon
`sk_stav_user_test_`	Personlig nøkkel	Test

Arbeidsområdenøkler tilhører arbeidsområdet. Eiere og administratorer oppretter dem.
Personlige nøkler tilhører ett medlem. De er tilgjengelige når en administrator i arbeidsområdet har aktivert dem under Arbeidsområdet ditt → Styr → Nøkkelpolicyer, som også kan kreve godkjenning (Arbeidsområdet ditt → Styr → Godkjenninger).
Begge typer faktureres til arbeidsområdets lommebok til katalogpris.
Miljøet er en del av nøkkelen, ikke URL-en. Live- og testnøkler kaller samme host.

Opprett begge under Arbeidsområdet ditt → Koble til → API-nøkler. En nøkkel vises én gang og lagres kun som en hash – mister du den, roter den.

Verifiser en nøkkel

curl https://api.stav.ai/v1/auth/validate \
  -H "Authorization: Bearer $STAV_API_KEY"

{
  "valid": true,
  "team_id": "…",
  "team_name": "Acme AS",
  "api_key_id": "…",
  "api_key_name": "prod-backend",
  "api_key_prefix": "sk_stav_live_",
  "environment": "PRODUCTION",
  "scopes": ["inference:chat", "inference:models"]
}

Ingen token, ingen kostnad. scopes er null når nøkkelen ikke har tilgangsbegrensninger.

Tilganger

Tilgang	Gir tilgang til
`inference:chat`	`POST /v1/chat/completions`, `POST /v1/responses`
`inference:messages`	`POST /v1/messages`, `POST /v1/messages/count_tokens`
`inference:embeddings`	`POST /v1/embeddings`
`inference:audio`	`POST /v1/audio/transcriptions`
`inference:models`	`GET /v1/models`, `GET /v1/models/{id}`

En nøkkel uten tilganger har full tilgang. Tilganger begrenser; de gir ikke tilgang utover det som er satt. Sett dem hvis du vil ha minste nødvendige tilgang.

Et kall utenfor nøkkelens tilganger:

{
  "error": {
    "message": "This API key does not have the 'inference:embeddings' scope.",
    "type": "permission_error",
    "code": "insufficient_scope"
  }
}

Mange IDE- og agentverktøy henter modellisten sin fra GET /v1/models. En nøkkel med bare inference:chat fullfører forespørsler, men returnerer 403 på den listen – legg til inference:models.

Andre viktige innstillinger

Utløp – en nøkkel som har passert expires_at, returnerer expired_api_key.
IP-tillatelsesliste – en forespørsel fra en annen adresse returnerer 403 ip_not_allowed.

Forespørselsgrenser

Per nøkkel, forespørsler per minutt, over et glidende 60-sekunders vindu:

Produksjonsnøkler: 300 rpm som standard
Testnøkler: 30 rpm som standard
En overstyring per nøkkel erstatter standardverdien

Når grensen nås:

HTTP 429
Retry-After: 3
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785667200

{
  "error": {
    "message": "Rate limit exceeded. Retry after 2.4 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Vent på Retry-After. Bare denne per-nøkkel-grensen sender X-RateLimit-*-headerne; en 429 uten dem kom fra et annet sted. Se Feil.

Autentiseringsfeil

Kode	Status	Årsak
`missing_api_key`	401	Ingen `Authorization: Bearer` og ingen `x-api-key`, eller et tomt token
`invalid_api_key`	401	Ikke en `sk_stav_`-nøkkel, ukjent eller trukket tilbake
`expired_api_key`	401	Nøkkelen har utløpt, eller en rotert nøkkel har passert karanteneperioden
`insufficient_scope`	403	Nøkkelen mangler tilgang til dette endepunktet
`ip_not_allowed`	403	Avsenderens IP-adresse er ikke på nøkkelens tillatelsesliste
`model_not_permitted`	403	Arbeidsområdets konfigurasjon tillater ikke den modellen
`rate_limit_exceeded`	429	Se ovenfor

401-svarene inneholder WWW-Authenticate: Bearer.

Rotering

Når du roterer en nøkkel, utstedes en ny, og den gamle fortsetter å virke i en karanteneperiode (7 dager som standard). Etter det returnerer den gamle nøkkelen expired_api_key.

Roter nøkkelen under Arbeidsområdet ditt → Koble til → API-nøkler og kopier den nye nøkkelen.
Rull den ut.
Sjekk Arbeidsområdet ditt → Overvåk → Forespørselslogg til den gamle nøkkelen ikke lenger har trafikk.
La karanteneperioden løpe ut, eller trekk tilbake den gamle nøkkelen.

Hvis en nøkkel lekker

Trekk den tilbake under Arbeidsområdet ditt → Koble til → API-nøkler. Filtrer deretter Arbeidsområdet ditt → Overvåk → Forespørselslogg på den nøkkelen for å se alle forespørslene den har gjort, med modell, token og kostnad.

God praksis

Én nøkkel per applikasjon. Tilskrivning og tilbaketrekking skjer per nøkkel.
Bruk en testnøkkel i CI.
Begrens tilgangene på nøkler som følger med i verktøy: inference:chat + inference:models dekker de fleste agentintegrasjoner.

Neste steg