Rotation och radering av nycklar
På denna sida
Rotation: Förnya utan avbrott
Rotation av nycklar är en kritisk säkerhetsåtgärd. Det genererar en ny hemlig nyckel som ersätter den gamla utan att själva nyckeln raderas. Den gamla hemligheten ogiltigförklaras omedelbart och permanent.
Utför en rotation
Rotation löser ett problem som radering inte kan: att förnya hemligheten utan att förlora nyckelns identitet. Dess ACL:er, hastighetsbegränsningar och namn bevaras vid operationen, så du behöver inte konfigurera om något – endast hemligheten ändras i ditt valv. Detta gör regelbunden rotation praktisk; att återskapa en nyckel skulle kräva att du konfigurerar om allt varje gång.
POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Beteende vid rotation
- Den gamla hemliga nyckeln ogiltigförklaras omedelbart – alla förfrågningar som använder den misslyckas med felkod 401
- En ny hemlig nyckel genereras och returneras i svaret
- Nyckel-ID:t (
apiKeyId), namn, ACL:er och hastighetsbegränsningar förblir oförändrade - Den nya hemliga nyckeln visas endast en gång – lagra den omedelbart
Säker rotationsprocess
En del av denna procedur förtjänar särskild betoning eftersom den ofta överraskar användare: den gamla hemligheten ogiltigförklaras omedelbart. Det finns ingen grace-period där båda hemligheterna fungerar. Tjänster som fortfarande använder det gamla värdet kommer att misslyckas sekund efter anropet. Detta styr ordningen på de sex stegen nedan: förbered ditt valv innan du utlöser rotationen, inte efteråt.
- Förbered din infrastruktur för att acceptera en ny nyckel (miljövariabel, valv)
- Utför rotationen via API:et
- Uppdatera hemligheten i ditt valv omedelbart
- Distribuera om dina tjänster med den nya nyckeln
- Verifiera att förfrågningar lyckas med den nya nyckeln
- Verifiera spridningen via
GET /auth/api-keys/{apiKeyId}/propagation
När ska du rotera?
Tre situationer utlöser rotation, var och en med olika brådska. Misstänkt läckage kräver omedelbar rotation: en teammedlem med nyckelåtkomst slutar, en logg som innehåller en nyckel exponeras offentligt, eller ett Git-arkiv innehåller en nyckel i klartext. I dessa fall är varje timmes väntan en timmes exponering, så rotera innan du slutför incidentanalysen. Policybaserad rotation är förebyggande: var 30:e, 60:e eller 90:e dag, beroende på dina säkerhetskrav, begränsar det livslängden för en nyckel som kan ha läckt obemärkt. Slutligen är miljöförändringar – infrastrukturmigration eller byte av leverantör – ett naturligt tillfälle att börja om med rena nycklar snarare än att bära med sig gamla in i en kontext de aldrig var designade för.
Radera en nyckel
Radering är permanent och oåterkallelig. Frågan du ska ställa innan du raderar är inte »Är denna nyckel komprometterad?« utan »Behöver jag fortfarande detta åtkomstomfång?«. Om svaret är ja behöver du rotation: det neutraliserar den exponerade hemligheten samtidigt som konfigurationen bevaras. Radering är bara motiverad för en nyckel som inte längre är användbar – ett stoppat projekt, en leverantör som slutat eller en avvecklad miljö.
DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Konsekvenser av radering
- Nyckeln och alla dess parametrar raderas permanent
- Alla förfrågningar som använder denna nyckel misslyckas omedelbart
- Åtgärden är oåterkallelig – du måste skapa en ny nyckel med nya parametrar
- Nyckelns användningshistorik förblir tillgänglig i analysverktygen
Rotation kontra radering
| Aspekt | Rotation | Radering |
|---|---|---|
| Nyckeln finns kvar | Ja | Nej |
| Ny hemlighet genereras | Ja | Nej |
| ACL:er bevaras | Ja | Nej |
| Begränsningar bevaras | Ja | Nej |
| Återkallelig | Nej (gammal hemlighet förlorad) | Nej (nyckel raderad) |
| Typisk användning | Regelbunden förnyelse | Föråldrad nyckel eller bekräftad kompromettering |
Automatisera rotation
Automatiserad rotation är bara meningsfull om skrivning till valvet ingår i samma skript, utan manuella ingrepp emellan. Annars flyttar du bara risken: en maskingenererad hemlighet som kopieras för hand hamnar lättare i urklipp eller terminalhistorik än en nyckel skapad från konsolen.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"
# Rotera
response = requests.post(
f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
new_key = response.json()
new_secret = new_key.get("secret")
# Lagra i ditt valv (exempel med en .env-fil)
# I produktion, använd Vault, AWS Secrets Manager, etc.
print(f"Ny nyckel genererad. Uppdatera ditt valv.")
Schemalagd rotation
Integrera rotation i din CI/CD-pipeline eller som ett cron-jobb:
# Cron-exempel: rotation den 1:a varje månad klockan 03.00
0 3 1 * * /opt/scripts/rotate-xai-keys.sh
Viktiga punkter
POST /auth/api-keys/{apiKeyId}/rotateogiltigförklarar den gamla hemligheten och genererar en ny- Ogiltigförklaring av den gamla hemligheten sker omedelbart och permanent
DELETE /auth/api-keys/{apiKeyId}raderar nyckeln oåterkalleligt- Föredra rotation framför radering för att behålla befintliga ACL:er och begränsningar
- Automatisera rotation med ett skript och ett hemlighetsvalv
- Verifiera alltid spridningen efter en rotation