Sleutels, capabilities en policy¶

Drie dingen bepalen wat een applicatie in Core mag. Een sleutel is hoe de applicatie zich meldt. Capabilities bepalen welke functies voor die sleutel bestaan. De policy bepaalt wat de sleutel binnen die functies bereikt: welke modellen, welke tools, welke kennis en welke gegevens.

Sleutels¶

Een API-sleutel hoort bij één organisatie en staat voor één applicatie. De applicatie stuurt de secret van de sleutel als bearer-token bij elk verzoek; er is geen inlog en geen tokenuitwisseling.

• Maak één sleutel per applicatie. Verbruik, limieten en het auditspoor worden per sleutel bijgehouden, dus zo zie je wie wat deed.
• De secret verschijnt één keer, bij het aanmaken. Raak je hem kwijt of lekt hij uit, dan roteer je de sleutel: de oude secret werkt direct niet meer, het id en de geschiedenis blijven.
• Een sleutel kan een kostenlimiet per maand en een vervaldatum hebben.
• GET /key geeft terug wat een sleutel is en mag: haar organisatie, capabilities en policy.

Personen die in de console inloggen zijn geen sleutels maar beheerders. Zij beheren de organisatie; een sleutel roept haar aan.

Capabilities¶

Een capability is een schakelaar voor een functie: threads voor gesprekken, tooling voor tools, knowledge voor kennis, agents voor agents. De volledige lijst staat in Capabilities.

Een capability werkt alleen als hij op twee plekken aanstaat:

1. in het plafond van de organisatie (Toegestane capabilities), en
2. op de sleutel zelf.

Het plafond zet de beheerder van de organisatie erboven. Op de sleutel kiest de beheerder van de organisatie zelf, binnen dat plafond. Staat een capability uit, dan antwoorden de routes erachter 404, hetzelfde antwoord als een pad dat niet bestaat.

Sommige capabilities hebben een andere nodig: geheugen vereist kennis, achtergrondruns vereisen gesprekken, artefacten vereisen bestanden. De capability management is anders dan de rest: een sleutel met management beheert de organisatie en de organisaties eronder via de API. Geef hem aan weinig sleutels.

Policy¶

Een capability zegt dat een sleutel tools mag gebruiken. De policy zegt welke. Een policy is een lijst regels, en elke regel staat één soort ding toe of verbiedt het:

Een regel kiest op naam (met een patroon zoals support-*) of op labels die je zelf aan resources hangt (zoals afdeling: support). Drie feiten bepalen de uitkomst:

• Verbieden gaat altijd voor.
• Zonder een regel die het toestaat, is iets niet toegestaan.
• De policy van de organisatie en die van de sleutel moeten het allebei toestaan. Een sleutel kan versmallen wat de organisatie toestaat, nooit verbreden.

Hangt de organisatie onder een andere, dan versmallen de policy's van de organisaties erboven dat verder: voor modellen, routers, tools, bestemmingen, het downloaden van artifacts en het schrijven van geheugen, en voor de toegestane regio's (Policy).

Wat geen regel toestaat, bestaat voor de sleutel niet: het ontbreekt in lijsten en een aanvraag met het id geeft 404.

Een regel kan ook de acties noemen waar hij over gaat: zien (lijst en lezen), gebruiken (in een beurt, een run of een aanroep), wijzigen (write in de API: aanmaken, bewerken, labels geven) en verwijderen. Een regel die er geen noemt, dekt ze allemaal. Met acties kan iedereen een agent gebruiken terwijl alleen beheerders hem wijzigen. Een ding dat de sleutel ziet maar niet mag gebruiken, wijzigen of verwijderen geeft 403, en dat geldt ook voor iets aanmaken, hernoemen of labels geven die geen regel toestaat: er is dan nog niets te verbergen. De tools die een sleutel bereikt, bepalen ook welke koppelingen, MCP-servers, scripts en toolsets hij toont als een verzoek een persoon noemt (Zien, gebruiken en wijzigen scheiden).

Een nieuwe sleutel begint met standaardregels die alle modellen, tools en bibliotheekonderdelen toestaan. Twee dingen staan standaard dicht tot je er een regel voor toevoegt: een beurt schrijft geen geheugen, en er wordt niets met een link gedeeld. Welke hosts een tool mag benaderen, bepaalt de organisatie met haar lijst Toegestane hosts; een sleutel zonder eigen regel daarover bereikt precies die hosts (Toegestane bestemmingen).

Naast regels heeft een policy instellingen. De belangrijkste:

• Agent verplicht: elke beurt moet een agent noemen en draait die zoals hij is vastgelegd. Voor een sleutel die je aan onbekenden geeft, zoals bezoekers van een chat op een website.
• Een subject is verplicht: elk verzoek moet de persoon noemen voor wie het is.
• Toegestane regio's: modellen, tools en andere bestemmingen buiten deze regio's worden geweigerd (Aanroepen binnen je regio's houden).

Per persoon: het subject¶

Gebruiken meerdere personen je applicatie met dezelfde sleutel, dan noemt elk verzoek de persoon voor wie het is: het subject, in de header X-Core-Subject. Het bevat een id dat jouw applicatie kiest en optionele attributen, zoals een afdeling. Regels in de policy kunnen daarvan afhangen: een persoon bereikt haar eigen gesprekken en de gedeelde, of alleen de kennisbronnen met het label van haar afdeling. Core beheert geen accounts voor deze personen; je applicatie levert de identiteit. Zie Bouwen voor personen.

Wanneer gebruik je wat¶

Hoe het samenhangt¶

• Een sleutel hoort bij één organisatie; het plafond en de policy van die organisatie gelden voor al haar sleutels.
• Wat een agent meebrengt, wordt getoetst aan de policy van de sleutel die hem aanroept. Een agent geeft een sleutel nooit meer bereik.
• Tools, kennis en modellen worden elk bereikt via een regel in de policy.
• Elke beslissing van de policy komt in het auditspoor (Inzicht).

Verder¶

Tutorial: Richt een nieuwe klantorganisatie in.

• Sleutels en policy in de console: een sleutel registreren, capabilities en policy instellen, roteren.
• Je eerste aanroep: GET /key lezen.
• Instellingen van een organisatie: het plafond en de policy van de organisatie.
• Organisaties beheren via de API: sleutels uitgeven via de API.
• Bouwen voor personen: subjects, labels en regels per persoon.
• Capabilities: de lijst.