Refresh JWT access token

Refresh the current user JWT access token with an optional custom validity period.

POST /api/sys/users/token/refresh

Refresh JWT access token

cURL

curl --request POST \
  --url https://spaces.nexudus.com/api/sys/users/token/refresh \
  --header 'Authorization: Basic <encoded-value>'

import requests

url = "https://spaces.nexudus.com/api/sys/users/token/refresh"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://spaces.nexudus.com/api/sys/users/token/refresh', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "WasSuccessful": true,
  "Value": {},
  "Status": 123,
  "Message": {},
  "Errors": "<any>",
  "401 Unauthorized": {},
  "AccessDenied": {}
}

Refresh JWT access token

Refreshes the authenticated user’s JWT access token, generating a new token and returning it in the response. This is useful when you need a fresh token with a different validity period than the original.

Authentication

Requires a valid customer bearer token via the Authorization header.

Request Body

Response

Returns an ActionConfirmation envelope.

WasSuccessful · boolean · required

true when the token was refreshed successfully.

Value · string | null

The new JWT access token string. Use this as the Authorization: Bearer value for subsequent API requests. null when WasSuccessful is false.

Status · number

HTTP-style status code mirrored in the response body. 200 on success, 500 on failure.

Message · string | null

Human-readable message. Usually "OK" on success.

Errors · any

Validation or server errors. null on success.

Examples

Refresh with default validity (30 minutes)

POST /api/sys/users/token/refresh
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{}

{
  "WasSuccessful": true,
  "Value": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.new_refreshed_token...",
  "Status": 200,
  "Message": "OK",
  "Errors": null
}

Refresh with custom validity (60 minutes)

POST /api/sys/users/token/refresh
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "ValidityInMinutes": 60
}

{
  "WasSuccessful": true,
  "Value": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.new_60min_token...",
  "Status": 200,
  "Message": "OK",
  "Errors": null
}

Admin Endpoint: Refresh Another User’s Token

An admin variant of this endpoint exists at POST /api/sys/users/{id}/token/refresh which allows refreshing the token for a specific user by ID.

Authentication

Requires a bearer token with ADMIN role or User-Edit permission.

URL Parameter

Request Body

Same as the current-user endpoint — optional ValidityInMinutes.

Example

POST /api/sys/users/42/token/refresh
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.admin_token...
Content-Type: application/json

{
  "ValidityInMinutes": 60
}

Use Cases

Extending token validity

When the default token validity is insufficient for a long-running operation, request a fresh token with an extended validity period:

const response = await fetch('/api/sys/users/token/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${currentToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ValidityInMinutes: 120 })
})

const result = await response.json()
if (result.WasSuccessful) {
  const newToken = result.Value
  // Use newToken for subsequent requests
}

Token rotation

Periodically refresh the access token to maintain a fresh validity window without requiring the user to re-authenticate.

Error Responses

401 Unauthorized · error

The bearer token is missing, expired, or invalid. The user must sign in again via POST /api/token.

AccessDenied · error

Returned when the authenticated user cannot be resolved from the token, or (for the admin endpoint) when the admin lacks access to the target user.

Related Endpoints

Method	Endpoint	Description
POST	/api/token	Exchange email and password (or a refresh token) for a new bearer token
POST	/api/sys/users/exchange	Exchange a server-issued JWT for a bearer token
POST	/api/sys/users/{id}/token/refresh	Admin: refresh another user’s token
GET	/api/auth/media/customer	Obtain a short-lived JWT for accessing protected media files