API-nycklar och OAuth
Allt du gör i Velrix går genom dess HTTP-API, på https://<realm>/api/<capability>/<event>. Tre sätt låter något annat än din webbläsare anropa det:
- en API-nyckel, för ett skript, ett CI-jobb eller en AI-agent;
- en OAuth-app, som frågar varje person vad den får göra åt dem;
- kommandot
velrix, som loggar in dig från din egen dator.
API-referensen och sidorna om Terraform, Ansible och MCP finns i realmens fönster Dokumentation (API-referensen i din realm).
Behörigheter
Alla tre ber om behörigheter (scopes): vad inloggningen får anropa.
| Behörighet | Ger |
|---|---|
compute | varje åtgärd i förmågan |
compute:* | samma sak, skrivet så att det inte kan tas för en inloggningsbehörighet |
compute.read | dess åtgärder som bara läser |
compute:app.list | exakt den åtgärden |
act_in_scopes | får ange en organisation du är medlem i, med dina rättigheter där |
E-post är förmågan email, men email ensamt är inloggningsbehörigheten för din adress. Be därför om e-post som email:* eller email.read.
En inloggning når aldrig mer än du själv gör. Utan act_in_scopes agerar den bara i ditt eget område, även om du är med i organisationer.
API-nycklar
Öppna API-nycklar (på din kontosida, eller en organisations sida för dess nycklar) och välj Ny nyckel.
- Ge den ett Namn du känner igen, till exempel
CI deploy. - Välj hur många dagar den ska gälla, högst 365. En nyckel kan inte förlängas: du skapar en ny.
- Kryssa i dess Behörigheter, och Skrivskyddad om den bara behöver läsa. På en personlig nyckel låter Agera i dina organisationer den arbeta i dina organisationer.
- Kopiera hemligheten. Den visas en gång; bara en hash av den sparas.
Skicka hemligheten som bearer token, Authorization: Bearer <hemlighet>, eller använd den som lösenord där en inloggning ber om ett, till exempel podman login mot registret.
En organisations nyckel agerar som personen som skapade den, bara inom organisationen och bara för det som kryssades i.
Håll nycklarna små
- Användning visar varje första användning från en adress eller för en åtgärd.
- Minsta behörighet bedömer nyckeln efter vad den faktiskt gjort: aldrig använd, inte använd på länge, bara läsningar, eller några få av sina åtgärder. Skapa en snävare nyckel gör en med bara det som användes.
- Återkalla stoppar en nyckel direkt.
En nyckel som skapats med en hel förmåga följer med nya versioner: åtgärder som en version lägger till ges till nyckeln, och åtgärder den tar bort försvinner. En nyckel med enstaka åtgärder blir aldrig bredare. Nyckelns sida säger när en version ändrade den.
OAuth-appar
Registrera en app
För en webbapp, ett kommandoradsverktyg eller en assistent som loggar in personer i din realm: öppna Anslutna appar och välj Registrera en app.
- Omdirigerings-URI:er matchas exakt:
https://, ellerhttp://127.0.0.1på valfri port för en app på personens egen dator. Inga alls för ett verktyg som bara loggar in med en enhetskod. - Konfidentiell för en server som kan hålla en hemlighet; appar på personers datorer är publika och bevisar vilka de är med PKCE.
- Behörigheter är det mesta appen får be om.
På https://<realm>/.well-known/openid-configuration hittar en app allt den behöver: realmen är en OAuth 2.1- och OpenID Connect-server.
När en app frågar dig
En app skickar dig till realmens inloggningssida. När du är inloggad visar ett kort appens namn, vem som registrerade den, vart den återvänder och vad den ber om. Kryssa ur det du inte vill att den ska få och välj Tillåt eller Neka. Realmen minns vad du tillät, så nästa inloggning frågar bara om något nytt.
Anslutna appar på din kontosida listar apparna du tillåtit. Återkalla avslutar direkt varje token appen har för dig.
Kommandot velrix
Kommandot velrix loggar in dig från vilken dator som helst och anropar API:t med dina rättigheter.
velrix login https://moln.exempel.se # öppnar webbläsaren
velrix login https://moln.exempel.se --device # ingen webbläsare här: en kod att skriva in på en annan enhet
velrix login https://moln.exempel.se --scope "sites databases email:* act_in_scopes"
velrix api sites:list
velrix api sites:create '{"scope":"org:acme","name":"shop"}'
En vanlig inloggning kan inte anropa något: lägg till det du behöver med --scope, så låter kortet i webbläsaren dig kryssa ur vad du vill. Kommandot förnyar sina token själv, och velrix logout avslutar sessionen i realmen. Med --profile håller du en inloggning per realm.
velrix access ger dig en inloggning till en app bakom Velrix Access, för git eller en TCP-tunnel; CLI-referensen listar alla kommandon.