API Token-Rotation

allgemeine Informationen

Passwork 7.6.0 führt zwei API-Endpunkte für die separate Rotation von accessToken und refreshToken sowie einen neuen Kontotyp ein: Dienstkonten. Die neuen Endpunkte sind für Sitzungen vom Typ API konzipiert. API-Sitzungen umfassen Dienstkontositzungen und Sitzungen, die im Abschnitt zur Benutzerauthentifizierung generiert wurden.

Standardmäßig gibt Passwork API-Antworten in Base64 zurück. Um JSON im Antworttext zu erhalten, fügen Sie den Header X-Response-Format: raw hinzu. Siehe API Antwortformat in den Übersichtsdokumenten. Die Felder accessTokenExpiredAt und refreshTokenExpiredAt enthalten die Ablaufzeit in Unix-Zeit. Die Antwort umfasst nur das Feld, das sich auf den rotierten Token bezieht (oder beide Felder für die Paarrotation).

Drehung	Endpunkt	Ergebnis
Paar	POST /api/v1/sessions/refresh	accessToken aktualisiert, refreshToken aktualisiert
accessToken	POST /api/v1/sessions/refresh-access-token	accessToken aktualisiert
RefreshToken	POST /api/v1/sessions/refresh-refresh-token	refreshToken aktualisiert

POST /api/v1/sessions/refresh

Gibt ein neues Paar aus accessToken und refreshToken zurück. Das alte Paar wird ungültig.

Beispiel anfordern

curl

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --header "Authorization: Bearer 7FmKp2nQ8vRt3WxYz9Bc1Dg4Hj6Lo5Ns0Ue+SmVaXoI=" \
  --data "{\"refreshToken\": \"2XkQp3oR9wSu4VyZa0Cd2Eh5Ik7Mp6Ot1Vf+TnWbYpJ=\"}" | jq .

Antwortbeispiel

{
  "accessToken": "9GnLq4pS0xTv5WzAb1De3Fi6Jl8Nq7Pu2Wg+UoXcZqK=",
  "refreshToken": "0HoMr5qT1yUw6XaBc2Ef4Gj7Km9Or8Qv3Xh/VpYdArL=",
  "accessTokenExpiredAt": 1775814596,
  "refreshTokenExpiredAt": 1782990596
}

Verhalten

1. Die Sitzung wird aus dem Header und Textkörper Authorization mit refreshToken aufgelöst.
2. Ein neues Token-Paar wird ausgegeben. Der bisherige wird ungültig.

POST /api/v1/sessions/refresh-access-token

Ein neues accessToken wird ausgegeben, während refreshToken auf dem Server nicht geändert wird. Verwenden Sie dies, wenn Sie einen kurzlebigen accessToken verlängern müssen, ohne refreshToken zu rotieren.

Beispiel anfordern

curl

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh-access-token" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --data "{\"accessToken\": \"JpNs6rWa2bXc8YdZ0ePq4fGh5Ij1Kl+Mn7Ro9StUvWx=\"}" | jq .

Antwortbeispiel

{
  "accessToken": "KqOt7sXb3cYd9ZeA1fQr5gHi6Jk2Lm+No8Sp0TuVwXy=",
  "accessTokenExpiredAt": 1775820103
}

Verhalten

1. Die Sitzung wird anhand des accessToken-Hashs aufgelöst.
2. Die Sitzung wird nicht gelöscht und refreshToken ist nicht abgelaufen.
3. accessToken darf zum Zeitpunkt der Anforderung nicht abgelaufen sein.
4. Es wird ein neuer accessToken ausgegeben. Der vorherige Token wird ungültig.

POST /api/v1/sessions/refresh-refresh-token

Ein neues refreshToken wird ausgestellt, während das aktuelle accessToken bis zu seinem eigenen Ablauf gültig bleibt. Verwenden Sie dies für eine langlebige refreshToken-Rotation, ohne eine bereits ausgestellte accessToken ungültig zu machen.

Beispiel anfordern

curl

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh-refresh-token" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --data "{\"refreshToken\": \"LrPu8tYc4dZe0AfB2gRs6hJk7Kl3Mn+Op9Tq1UvWxYz=\"}" | jq .

Antwortbeispiel

{
  "refreshToken": "MsQv9uZd5eAf1BgC3hSt7iKl8Lm4No+Pq0Ur2VwXzA0=",
  "refreshTokenExpiredAt": 1782999124
}

Verhalten

1. Die Sitzung wird anhand des refreshToken-Hashs aufgelöst.
2. Die Sitzung wird nicht gelöscht und refreshToken ist nicht abgelaufen.
3. Es wird ein neuer refreshToken ausgegeben. Der vorherige Token wird ungültig.