Sleutels en policy in de console¶

Het concept achter sleutels en policy staat in Sleutels, capabilities en policy.

In het onderdeel Sleutels registreer je een API-sleutel voor elke applicatie die Core aanroept. Je stelt er haar capabilities, limiet en policy in, roteert een secret en trekt een sleutel in. Een sleutel aanmaken via de API staat in Sleutels uitgeven, roteren en intrekken.

Je hebt een beheerdersaccount van de organisatie nodig. Houdt de organisatie erboven het sleutelbeheer bij zich, dan kun je sleutels lezen en niet wijzigen (Voorbehouden sleutelbeheer).

Een sleutel aanmaken en de secret bewaren¶

1. Kies Sleutel registreren. Het formulier opent als eigen pagina, in drie stappen.
2. Vul bij Naam en grenzen een naam in, en zo nodig een limiet en een vervaldatum. De naam van een sleutel is uniek binnen de sleutels van je organisatie: een sleutel registreren onder een naam die een andere sleutel al heeft, of hem zo hernoemen, wordt met 409 geweigerd.
3. Schakel bij Wat mag deze sleutel? de capabilities in die de applicatie nodig heeft.
4. Beperken is optioneel: de policy en de fallback-routering staan dichtgeklapt tot je ze opent, en je kunt ze later op de pagina van de sleutel wijzigen. Naast het formulier staan het plafond van de organisatie en waarop deze sleutel terugvalt.
5. Kies Registreren in de balk onderaan, kopieer de secret uit het venster en bewaar hem veilig. Sluit je het venster, dan sta je weer in de lijst.
6. Deel de secret met de applicatiebeheerder via jullie gebruikelijke manier om inloggegevens over te dragen.

Core kan de secret niet opnieuw tonen. Ben je hem kwijt, roteer dan de sleutel om een nieuwe secret te maken. Het venster sluit alleen via de eigen knop; Esc en klikken buiten het venster sluiten het niet.

In de kolom Sleutel staat onder de naam de prefix, de eerste twaalf tekens, om de sleutel te herkennen. Met de prefix kun je geen verzoek authenticeren. Er staat daarom geen kopieerknop naast. Het zoekveld boven de tabel zoekt op naam en prefix in de geladen sleutels. Onder de tabel staat hoeveel sleutels er zijn, hoeveel verlopen zijn en hoeveel binnen 30 dagen verlopen; staan er meer sleutels dan er geladen zijn, dan tellen die getallen alleen de geladen sleutels.

In een smaller venster toont de lijst minder kolommen (eerst vervallen Limiet / maand en Geregistreerd, daarna Capabilities); de pagina van een sleutel toont ze altijd.

Capabilities¶

Schakel capabilities in op de pagina van de sleutel, of bij het registreren. Je kunt alleen capabilities inschakelen die de organisatie toestaat. Uitschakelen op deze pagina heeft alleen gevolgen voor deze sleutel.

De console controleert afhankelijkheden: geheugen vereist kennis, achtergrondruns vereisen gesprekken, tasks en workflows vereisen achtergrondruns en gesprekken, en artefacten vereisen bestanden. Schakel eerst de benodigde capability in en daarna de functie die ervan afhangt. De configuratievelden van memory zelf -- zoek- en schrijftools, automatisch toevoegen, afname -- staan op Geheugen via de API.

Schakel management in en deze sleutel beheert de organisatie zelf via de API — hernoemen, sleutels uitgeven, onderliggende organisaties aanmaken en beheren — net zoals een beheerder dat hier doet; geef hem aan weinig sleutels, want zo'n sleutel kan een nieuwe sleutel met management registreren (toegestane capabilities). Wat de sleutel daarna vanuit de API kan, staat op Organisaties beheren via de API.

Schakel je tooling in, dan verschijnt daaronder een tweede lijst: de systeemtools die deze sleutel mag gebruiken. Elke tool staat standaard uit totdat je hem hier aanvinkt. Wat elke tool doet, staat op Tools via de API (subagent), daar (pagina's ophalen en zoeken), daar (afbeeldingen genereren), daar (Document schrijven), daar (Audio transcriberen), daar (Bestanden tonen, Bestanden verplaatsen, Bestanden hernoemen en Bestanden verwijderen, elk een eigen vinkje, zodat het model bestanden kan opsommen zonder ze te mogen wijzigen) en op Computers via de API (Computer gebruiken, waarvoor de sleutel ook de capability computer nodig heeft). Platformlogboek lezen staat alleen bij sleutels van de supportorganisatie van het platform, de enige organisatie die hem mag gebruiken. Een sleutel elders die de schakelaar al heeft, toont hem nog, aangevinkt, zodat je hem kunt uitzetten; daar doet hij niets. In de supportorganisatie verloopt een sleutel met Platformlogboek lezen, Platformtrace lezen of Platformalerts lezen binnen zeven dagen: het formulier vraagt Verloopt op voordat het opslaat, en Core weigert zo'n sleutel zonder. Registreer een nieuwe sleutel als hij verlopen is.

Onder de systeemtools laat Tool zoeken de beurten van deze sleutel hun tools via de toolrouter aanbieden in plaats van allemaal tegelijk; de velden staan op Een agent met veel tools.

trust_envelope bepaalt wat het model te horen krijgt, niet wat de sleutel mag bereiken: staat hij aan, dan beginnen de beurten van deze sleutel met de inleiding van Core en staat elk gebruikersbericht en elk toolresultaat in <untrusted>, zodat het model weet welke tekst gegevens zijn. Op een nieuwe sleutel staat hij uit. Laat hem uit voor een sleutel die een codeeragent gebruikt; zet hem aan voor een sleutel waarvan de beurten documenten lezen die niemand heeft nagekeken en tools aanroepen die iets veranderen. Bij sleutels die al bestonden voordat de capability werd ingevoerd, staat hij aan. Zie De capability trust_envelope.

Limiet per maand¶

Naast de naam staat Kostenlimiet per maand (euro): een plafond op wat deze ene sleutel in één kalendermaand (UTC) mag verbruiken, geteld over alles wat een prijs heeft -- tokens, afbeeldingen, toolaanroepen, zoekopdrachten, verwerkte pagina's, gecrawlde pagina's en sandboxtijd. Wat de sleutel opslaat hoort daar niet bij: opslag is een meter en telt nooit mee tegen de limiet. Je vult het in bij het registreren en je wijzigt het op de pagina van de sleutel.

• Leeg is geen limiet.
• 0 is een echte limiet: de sleutel verbruikt dan niets met een prijs meer tot de maand omslaat.
• Maak je het veld leeg bij het bewerken, dan vervalt de limiet.
• Schrijf het bedrag met een punt, bijvoorbeeld 250.00; dat is wat Core bewaart, tot op de cent.

De limiet van de organisatie zelf (Instellingen) geldt daarnaast altijd: een ruimere limiet op een sleutel maakt die van de organisatie niet ruimer. Wat er is verbruikt, staat per sleutel op Gebruik.

Vervaldatum¶

Naast de limiet staat een optionele Verloopt op: het moment waarop deze sleutel stopt met aanroepen authenticeren. Je zet hem bij het registreren of wijzigt hem op de pagina van de sleutel.

• Leeg is nooit -- de sleutel werkt tot je haar zelf roteert, verwijdert of laat verlopen.
• Kies een moment in de toekomst; een moment dat al voorbij is wordt geweigerd.
• Maak je het veld leeg bij het bewerken, dan vervalt de vervaldatum.

Voorbij dat moment wordt de sleutel geweigerd zoals een onbekende sleutel: dezelfde 401, niemand die ermee aanroept krijgt te horen dat hier ooit een sleutel bestond, en een subject-token dat op deze sleutel is gemunt stopt op precies hetzelfde moment als de sleutel zelf. Roteren zet de vervaldatum nooit terug -- roteren vervangt de secret, niet de levensduur.

Policy¶

De policy van een sleutel bepaalt wat de sleutel binnen haar organisatie bereikt: welke modellen, tools en bestemmingen, welke prompts, skills, agents en kennis, en welke gesprekken, geheugen, bestanden en datastore-rijen. Core controleert de policy bij elk verzoek. Een applicatie leest haar eigen policy met GET /key.

Op de pagina van een sleutel, en bij het registreren onder Beperken, bestaat de policy uit twee kaarten: Regels, één lijst met regels, en Instellingen. Elke regel staat één soort ding toe of verbiedt het. Drie feiten bepalen wat de lijst betekent:

• Verbieden gaat altijd voor. Wat een regel verbiedt, staat geen andere regel toe.
• Zonder een regel die het toestaat, is iets niet toegestaan. Een lege lijst staat niets toe.
• Het document van de organisatie en dat van de sleutel moeten het allebei toestaan. Heeft de organisatie een eigen policy, dan kan een sleutel versmallen wat daar staat en nooit verbreden.

De regels hebben geen volgorde, dus er valt niets te sorteren: een regel hoger of lager zetten zou niets veranderen.

De lijst lezen¶

Elke rij is één regel. Je ziet een label Toestaan of Verbieden, de regel als zin, en onder de zin de naam van de regel. Een regel zonder naam heet naar zijn plaats in de lijst, geteld vanaf 0, zoals regel 3. Het auditspoor gebruikt dezelfde naam.

De rijen staan gegroepeerd onder de soort waarover ze gaan. Met de knoppen boven de lijst filter je: Alles, Modellen, Tools en bestemmingen, Bibliotheek, Kennis en Gegevens, elk met het aantal regels erin.

Wat geen regel toestaat, bestaat voor de sleutel niet: het ontbreekt in lijsten, een directe aanvraag of een verwijzing ernaar geeft 404, en een model of een tool wordt de beurt niet aangeboden. Wat de regels de sleutel laten zien maar niet laten gebruiken, wijzigen of verwijderen, geeft 403 voor die actie, en dat geldt ook voor een resource aanmaken, hernoemen of labels geven die geen regel voor Wijzigen toestaat (Acties). Wat onder een resource hangt, volgt haar, zoals de bronnen van een collectie en de geheugenrecords van een index. Geweigerde directe verwijzingen worden vastgelegd in het auditspoor.

De standaardregels¶

De lijst van een nieuwe sleutel begint met de standaardregels van Core, elk met een eigen naam. Ze staan al op het registratieformulier, zodat je ze kunt wijzigen of verwijderen voordat je de sleutel registreert.

Onder de standaardregels schrijft een beurt dus geen geheugen en wordt er niets met een link gedeeld, totdat je een regel toevoegt die het toestaat.

Bestemmingen werken anders dan de andere soorten. De organisatie bepaalt welke hosts bereikt mogen worden, op de kaart Toegestane hosts. Een sleutel zonder eigen regel Toestaan over Bestemmingen bereikt precies die hosts. Voeg je zo'n regel toe, dan bereikt de sleutel alleen de hosts die de regel noemt en die de organisatie ook toestaat. Een regel Verbieden haalt hosts weg en heeft geen regel Toestaan ernaast nodig.

Terug naar standaard zet de standaardregels terug in de lijst, in plaats van wat er staat. Net als elke andere wijziging in de lijst wordt dat pas opgeslagen wanneer je het formulier opslaat.

Verwijder je elke regel, dan zegt de lijst Er staat geen enkele regel: niets is toegestaan tot je er een toevoegt. Dat is een geldige policy: de sleutel bereikt dan niets.

Een regel toevoegen of wijzigen¶

1. Kies Regel toevoegen onder de lijst, of het penpictogram op een rij. Er opent een lade.
2. Kies onder Wat de regel doet voor Toestaan of Verbieden. Een regel over Beurten zonder agent biedt alleen Verbieden.
3. Kies onder Waarover de soort.
4. Vul desgewenst een Naam van de regel in: kleine letters, cijfers en streepjes, beginnend met een letter, hoogstens 64 tekens, en anders dan elke andere regel in de lijst.
5. Vul de onderdelen in die bij de soort horen (hieronder).
6. Kies Overnemen. De lade sluit en de rij verandert in de lijst.
7. Sla het formulier op: Opslaan op de pagina van een sleutel, Registreren bij een nieuwe sleutel. De regel geldt pas nadat het formulier is opgeslagen.

Het prullenbakpictogram op een rij verwijdert de regel, ook weer zodra je het formulier opslaat.

Een regel heeft vier onderdelen. De lade biedt alleen de onderdelen aan die bij de gekozen soort horen en zegt het erbij als er een ontbreekt, bijvoorbeeld Deze soort heeft geen naam om op te letten.

Een lijst bevat hoogstens 500 regels, en een regel hoogstens 200 patronen, 16 labels en 16 voorwaarden.

De zin van de rij eindigt met de acties, zoals …: zien en gebruiken. Geen actie omvat een andere: een regel voor alleen Wijzigen laat een persoon het ding niet vinden, dus vink Zien erbij aan. Een persoon die een ding ziet maar niet mag wijzigen, wordt geweigerd met 403; wie het niet mag zien, krijgt 404. Het uitgewerkte voorbeeld scheidt zo het gebruiken van agents van het wijzigen ervan.

Zeven wijzigingen die vaak voorkomen:

• Eén tool wegnemen. Voeg een regel Verbieden toe over Tools met het patroon builtin__web_search. De standaardregel die elke tool toestaat mag blijven staan: verbieden gaat voor.
• Tools een API laten aanroepen. Sta de host toe op de kaart Toegestane hosts van de organisatie, zoals api.tickets.example.com. De sleutel heeft er geen eigen regel voor nodig.
• Eén sleutel tot enkele hosts beperken. Voeg een regel Toestaan toe over Bestemmingen met de hostnamen die deze sleutel mag bereiken. De organisatie moet ze ook toestaan.
• De sleutel tot enkele prompts beperken. Wijzig de standaardregel prompt en voeg het patroon support-* toe. De sleutel bereikt dan alleen prompts waarvan de naam met support- begint.
• Beurten geheugen laten schrijven. Voeg een regel Toestaan toe over Schrijven naar geheugen. De policy van de organisatie moet het ook toestaan.
• Alleen beheerders agents laten wijzigen. Wijzig de standaardregel agent en vink Zien en Gebruiken aan. Voeg een regel Toestaan toe over Agents met Zien, Wijzigen en Verwijderen aangevinkt en, onder Wanneer, de voorwaarde Een attribuut van de persoon bevat een waarde met role en admin. Maakt of wijzigt een backendtaak die niemand noemt agents, voeg dan een derde regel Toestaan over Agents toe met de voorwaarde Het verzoek noemt niemand en geen actie aangevinkt.
• Een basisabonnement van het kale model afhouden. Voeg een regel Verbieden toe over Beurten zonder agent met, onder Wanneer, de voorwaarde Een attribuut van de persoon bevat een waarde met plan en basic. De beurten van die personen moeten dan een agent noemen; hun toolaanroepen en kenniszoekopdrachten blijven toegestaan. Regels kennen geen «niet»: noem het abonnement dat je inperkt, nooit «iedereen behalve pro».

Regels over een persoon¶

Een verzoek kan de persoon noemen voor wie het is, het subject. Met het onderdeel Wanneer laat je een regel van die persoon afhangen. Een voorwaarde is een van deze vier:

Een voorwaarde die de persoon leest, geldt nooit voor een verzoek dat niemand noemt. Zo'n regel staat dan niets toe en verbiedt niets.

Zo laat je een persoon bereiken wat bij haar afdeling hoort:

1. Geef de resources een label, bijvoorbeeld afdeling: support.
2. Voeg een regel Toestaan toe over de soort, bijvoorbeeld Kennisbronnen.
3. Voeg onder Wanneer de voorwaarde Label is een van de waarden van de persoon toe, met het label afdeling en het attribuut afdeling.

Regels die toestaan tellen op. Laat bij Gesprekken, Geheugenrecords, Opgeslagen bestanden en Datastore-rijen de drie standaardregels staan en voeg de jouwe toe: een persoon bereikt dan haar eigen rijen, de gedeelde en die van haar afdeling. Bij een soort waarvan de standaardregel alles toestaat, zoals Kennisbronnen of Tools, staat die standaardregel ook elke persoon alles toe. Wil je per persoon versmallen, verwijder hem dan en voeg naast je eigen regel een regel toe met de voorwaarde Het verzoek noemt niemand, zodat een achtergrondtaak die geen persoon noemt alles blijft bereiken. Je eerste regel schrijven werkt dit voorbeeld uit.

Heeft de organisatie een labelvocabulaire, dan kies je het label, het attribuut en een waarde uit een vaste set uit een lijst in plaats van ze te typen.

Instellingen¶

De kaart Instellingen bevat wat de policy zegt dat geen regel is.

Een subject is verplicht weigert elk verzoek dat geen persoon noemt met 422 -- 400 op /responses en /messages, die de foutvorm van de leverancier teruggeven (Verzoeken). Zonder deze instelling wordt zo'n verzoek beslist door de regels die voor niemand gelden.

Agent verplicht zorgt dat elke beurt onder deze sleutel een van de agents noemt die de regels toestaan, en die draait zoals hij is gedefinieerd. Elk van deze wordt geweigerd met 403 voordat er een model wordt aangeroepen:

• een beurt op POST /responses of POST /messages die geen agent noemt;
• een beurt die iets aan haar agent toevoegt: tools, skills, instructions of een prompt op POST /responses, system, tools of skills op POST /messages. Een veld dat de agent vastlegt wordt geweigerd met 400, zoals onder elke sleutel. Het model, de temperatuur en de tokenlimiet mag je nog zetten waar de agent ze openlaat;
• een directe toolaanroep, een toolset die via MCP wordt aangeboden, en een kenniszoekopdracht, een zoektool-aanvraag of een pipelinetest buiten een beurt (Kennis).

Gebruik het voor een sleutel die je aan onbekenden geeft, zoals de bezoekers van een chat op je site: elke beurt draait dan een agent die jij hebt gedefinieerd, met zijn instructies en zijn tools en niets meer. De schakelaar kan niet aan staan zolang geen regel een agent toestaat; het formulier zegt dan Geen regel staat een agent toe. Voeg er een toe, of zet Agent verplicht uit. Vereist de policy van de organisatie een agent, dan geldt dat voor elke sleutel van de organisatie, wat de eigen schakelaar ook zegt. Zie Agents.

Labels die een persoon mag schrijven bewaakt de labels die je regels lezen. Kies Label toevoegen, kies de Soort rij (Gesprekken, Geheugenrecords, Kennisbronnen, Opgeslagen bestanden of Datastore-rijen), het Label, en onder Moet gelijk zijn aan waar een geschreven waarde aan moet voldoen: Het eigen id van de persoon, Een waarde van een attribuut of Een vaste waarde. Een verzoek dat een persoon noemt en een andere waarde onder dat label schrijft, krijgt 422. Een label dat er niet staat is vrij, en een label dat een rij al draagt behouden of weghalen mag altijd (Welke labels een persoon mag schrijven).

Langste levensduur van een deellink (dagen) (share_link_max_days) is een heel getal van 1 tot en met 365. Een deellink die langer wordt gevraagd, wordt geweigerd. Leeg betekent dat dit document geen grens noemt; de kortste grens die het document van de organisatie en dat van de sleutel noemen geldt, en 30 dagen als geen van beide er een noemt. Het veld wordt alleen gelezen waar een regel delen met een link toestaat.

Uitgefaseerde modellen (deprecated_models) bepaalt wat een beurt krijgt die een model noemt waarvan de uitfaseerdatum voorbij is: Omleiden naar de vervanger (reroute) laat haar op de vervanger draaien, Blokkeren (block) weigert haar met de datum en de vervanger. Niets ingesteld (omleiden) laat dit document zonder keuze. Blokkeren geldt zodra het document van de organisatie of dat van de sleutel het zegt; zegt geen van beide iets, dan wordt er omgeleid. Zie Uitgefaseerde modellen.

Waar gegevens heen mogen bevat drie lijsten. Een regio is eu, us, in-cluster, global of een landcode van twee letters, zoals nl.

Zie Aanroepen binnen je regio's houden en Hosting.

Fallback-routering¶

Met Fallback-routering stel je in of Core een ander model mag proberen wanneer het gevraagde model niet kan antwoorden. De schakelaar staat standaard aan. Uitschakelen blokkeert fallback voor deze sleutel, ook als de organisatie een routeringsconfiguratie heeft.

Bij het registreren staat dit onder Beperken; klik op de rij om hem te openen. Kies onder Routeringsconfiguratie:

• Standaard van de organisatie om de configuratie op het Instellingen te gebruiken.
• Een eigen configuratie om voor deze sleutel van de organisatiestandaard af te wijken.

Onder het veld staat welke configuratie nu in gebruik is, of dat er geen fallback is ingesteld. Maak configuraties bij Routering. Het gedrag en de beperkingen staan bij Terugvallen op een ander model.

Een sleutel roteren¶

Kies Roteren om voor een bestaande sleutel een nieuwe secret te maken. Kopieer die uit het bevestigingsvenster; de secret wordt één keer getoond. Het id, de capabilities, het beleid en de gebruiksgeschiedenis blijven behouden.

Roteren twee mensen dezelfde sleutel op hetzelfde moment, dan wordt de tweede met 409 geweigerd ("This key is being changed by another request"): lees de sleutel opnieuw en roteer nog eens als dat nog nodig is.

De vorige secret werkt niet meer zodra het roteren klaar is. Werk alle applicaties die de sleutel gebruiken direct bij; er is geen periode waarin beide secrets werken.

Roteren laat het callbackgeheim van de sleutel ongemoeid. De console heeft geen bediening voor het callbackgeheim: het wordt alleen via de API aangemaakt en vervangen (Een callback verifiëren).

Roteer bij een uitgelekte of verlopende credential. Maak voor een andere applicatie een aparte sleutel aan. Als je een sleutel verwijdert en een nieuwe registreert, krijgt die een nieuw id. Eerdere verbruiks- en auditgegevens blijven bij het oude id horen.

Een sleutel bewerken of verwijderen¶

Klik op een rij om de sleutel te openen. Bovenaan staan de status (Actief of Verlopen), de prefix, wanneer de sleutel is geregistreerd en gewijzigd, en de limiet, de vervaldatum en het aantal capabilities. Links staan de onderdelen van de pagina: Algemeen, Capabilities, Policy, Fallback-routering, Verbinden via MCP en Gevarenzone. Wijzig je iets, dan telt de balk onderaan de wijzigingen; Opslaan bewaart ze, Annuleren zet ze terug. Roteren staat in de balk bovenaan, Verwijderen in de gevarenzone. Beide staan ook in het rijmenu van de lijst, voor als je al weet welke sleutel je bedoelt.

Een opslag die de policy van de sleutel wijzigt, wordt geweigerd als iemand anders die policy heeft opgeslagen nadat jij de pagina opende. De pagina toont dan Het document is intussen gewijzigd. Je wijzigingen staan nog op het scherm en zijn niet opgeslagen; Opgeslagen document laden leest de sleutel opnieuw en gooit ze weg, dus noteer ze eerst (dezelfde melding bij de policy van een organisatie). Alleen een opslag die de policy wijzigt, kan zo worden geweigerd: een nieuwe naam, limiet of capability wordt opgeslagen, wat er intussen ook met de policy is gebeurd.

Op een telefoon is de pagina een inhoudsopgave: elk onderdeel is een rij met een korte samenvatting en opent een eigen scherm met Opslaan onderaan. Sleutel verwijderen is de laatste rij.

Verwijderen blokkeert direct verdere aanroepen met de sleutel. Resources die ermee zijn aangemaakt blijven beschikbaar voor de organisatie.

Voorbehouden sleutelbeheer¶

Als de bovenliggende organisatie het sleutelbeheer heeft voorbehouden, kun je sleutels en hun instellingen bekijken maar niet wijzigen. Registreren, opslaan, roteren en verwijderen zijn dan niet beschikbaar.

Vraag een operator of beheerder van de bovenliggende organisatie om de wijziging uit te voeren. Deze beperking geldt ook voor sleutels met management.

Verbinden via MCP¶

De eigen pagina van een sleutel bevat na de fallback-routering een onderdeel Verbinden via MCP: het endpoint /api/v1/mcp, alleen-lezen met een kopieerknop. De tools die een MCP-client daar ziet zijn precies de operaties die de ingeschakelde capabilities van deze sleutel toestaan. Zie Core vanuit een MCP-client gebruiken voor hoe je Claude Code, Cursor of een andere client met de secret van deze sleutel verbindt.

Auditregistraties¶

Het beheerauditspoor bevat key.registered, key.updated, key.rotated, key.callback_secret_created, key.callback_secret_rotated, key.disabled, key.enabled en key.deleted, met het sleutel-id en de actor. Deze gebeurtenissen bevatten niet de secret, de hash, de prefix of het callbackgeheim.