API token rotation

General information

Passwork 7.6.0 introduces two API endpoints for separate rotation of accessToken and refreshToken, plus a new account type: service accounts. The new endpoints are designed for sessions of type API. API sessions include service account sessions and sessions generated in the user authentication section.

By default, Passwork returns API responses in Base64. To get JSON in the response body, add the X-Response-Format: raw header. See API response format in the overview docs. The accessTokenExpiredAt and refreshTokenExpiredAt fields contain expiration time in Unix time. The response includes only the field related to the rotated token (or both fields for pair rotation).

Rotation	Endpoint	Result
Pair	POST /api/v1/sessions/refresh	accessToken updated, refreshToken updated
accessToken	POST /api/v1/sessions/refresh-access-token	accessToken updated
refreshToken	POST /api/v1/sessions/refresh-refresh-token	refreshToken updated

POST /api/v1/sessions/refresh

Returns a new pair of accessToken and refreshToken. The old pair becomes invalid.

Request example

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 .

Response example

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

Behavior

1. The session is resolved from the Authorization header and body with refreshToken.
2. A new token pair is issued. The previous one becomes invalid.

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

A new accessToken is issued, while refreshToken on the server is not changed. Use this when you need to extend a short-lived accessToken without rotating refreshToken.

Request example

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 .

Response example

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

Behavior

1. The session is resolved from the accessToken hash.
2. The session is not deleted and refreshToken is not expired.
3. accessToken must not be expired at request time.
4. A new accessToken is issued. The previous token becomes invalid.

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

A new refreshToken is issued, while the current accessToken remains valid until its own expiration. Use this for long-lived refreshToken rotation without invalidating an already issued accessToken.

Request example

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 .

Response example

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

Behavior

1. The session is resolved from the refreshToken hash.
2. The session is not deleted and refreshToken is not expired.
3. A new refreshToken is issued. The previous token becomes invalid.

LLM version