Kom i gang

Autentificering og API-nøgler

Nøgletyper og præfikser, hvor du opretter dem, adgange, forespørgselsgrænser, rotering, og hvad hver autentificeringsfejl betyder.

Sådan sender du nøglen

Authorization: Bearer sk_stav_live_...

x-api-key: sk_stav_live_... fungerer også, da det er sådan, Anthropics SDK sender sin nøgle. Hvis begge headere er til stede, vinder Authorization.

Base-URL for alle API'er: https://api.stav.ai/v1.

Nøgletyper

Præfiks	Type	Miljø
`sk_stav_live_`	Arbejdsområdenøgle	Produktion
`sk_stav_test_`	Arbejdsområdenøgle	Test
`sk_stav_user_live_`	Brugernøgle	Produktion
`sk_stav_user_test_`	Brugernøgle	Test

Arbejdsområdenøgler tilhører arbejdsområdet. Ejere og administratorer opretter dem.
Brugernøgler tilhører ét medlem. De er tilgængelige, når en administrator for arbejdsområdet har aktiveret dem under Dit arbejdsområde → Styr → Nøglepolicyer, hvilket også kan kræve godkendelse (Dit arbejdsområde → Styr → Godkendelser).
Begge typer trækkes fra arbejdsområdets tegnebog til katalogpris.
Miljøet er en del af nøglen, ikke URL'en. Live- og testnøgler kalder samme host.

Opret begge dele i Dit arbejdsområde → Forbind → API-nøgler. En nøgle vises kun én gang og gemmes kun som en hash — hvis du mister den, skal du rotere den.

Bekræft en nøgle

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 tokens, ingen omkostninger. scopes er null, når nøglen ikke har nogen begrænsninger på sin adgang.

Adgange (scopes)

Adgang	Giver adgang 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`, `POST /v1/audio/speech`
`inference:decisions`	`POST /v1/decisions`
`inference:rerank`	`POST /v1/rerank`
`inference:models`	`GET /v1/models`, `GET /v1/models/{id}`, `GET /v1/models/{id}/endpoints`

En nøgle uden valgte adgange har fuld adgang. Scopes begrænser; de tildeler ikke rettigheder. Indstil dem, hvis du ønsker mindst mulige privilegier.

Et kald uden for nøglens adgang:

{
  "error": {
    "message": "Denne API-nøgle har ikke adgangen 'inference:embeddings'. Tilføj den til nøglen under Dit arbejdsområde → Forbind → API-nøgler.",
    "type": "permission_error",
    "code": "insufficient_scope"
  }
}

Visning af modeller er sin egen adgang. En nøgle med eksplicit definerede adgange kan kun kalde GET /v1/models, hvis inference:models er en af dem. Dette gælder for alle API'er: En nøgle med kun inference:chat, kun inference:decisions eller kun inference:embeddings får besvaret sine egne forespørgsler, men får en 403 på modellisten. Mange SDK'er, IDE'er, agentværktøjer og testmiljøer kalder denne liste først, så tilføj inference:models til samme nøgle — en nøgle kan indeholde flere adgange.

Andre vigtige indstillinger

Udløb — en nøgle efter expires_at returnerer expired_api_key.
IP-tilladelsesliste — en forespørgsel fra enhver anden adresse returnerer 403 ip_not_allowed.

Forespørgselsgrænser

Per nøgle, forespørgsler per minut, over et glidende 60-sekunders vindue:

Produktionsnøgler: 300 rpm som standard
Testnøgler: 30 rpm som standard
En overstyring per nøgle erstatter standardværdien

Når grænsen er nået:

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. Kun denne grænse per nøgle sender X-RateLimit-*-headere; en 429 uden disse kom fra et andet sted. Se Fejl.

Godkendelsesfejl

Kode	Status	Årsag
`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øgle, ukendt eller tilbagekaldt
`expired_api_key`	401	Efter sit udløb, eller en roteret nøgle efter sin overgangsperiode
`insufficient_scope`	403	Nøglen mangler adgang til dette endepunkt
`ip_not_allowed`	403	Afsenderens IP er ikke på nøglens tilladelsesliste
`model_not_permitted`	403	Dit arbejdsområdes indstillinger tillader ikke den model
`rate_limit_exceeded`	429	Se ovenfor

401-fejl indeholder WWW-Authenticate: Bearer.

Rotering

Rotering af en nøgle udsteder en ny og lader den gamle fungere i en overgangsperiode (som standard 7 dage). Derefter returnerer den gamle nøgle expired_api_key.

Roter nøglen under Dit arbejdsområde → Forbind → API-nøgler og kopiér den nye nøgle.
Tag den i brug.
Kontrollér Dit arbejdsområde → Overvåg → Forespørgselslog, indtil den gamle nøgle ikke har mere trafik.
Lad overgangsperioden udløbe, eller tilbagekald den gamle nøgle.

Hvis en nøgle lækker

Tilbagekald den under Dit arbejdsområde → Forbind → API-nøgler. Derefter kan du filtrere Dit arbejdsområde → Overvåg → Forespørgselslog efter den nøgle for at se hvert kald, den har foretaget, med model, tokens og forbrug.

God praksis

Én nøgle per applikation. Sporing og tilbagekaldelse sker per nøgle.
Brug en testnøgle i CI.
Begræns adgangen for nøgler, der sendes med i værktøjer: inference:chat + inference:models dækker de fleste agent-integrationer. Uanset hvilket API en nøgle er til, bør du tilføje inference:models, hvis værktøjet viser lister over modeller.

Næste skridt