> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh JWT access token

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

# 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

<RequestBodyField name="ValidityInMinutes" type="number" default="30">
  Optional. The validity period of the new token in minutes. Defaults to `30` if omitted or `null`.
</RequestBodyField>

## Response

Returns an `ActionConfirmation` envelope.

<ResponseField name="WasSuccessful" type="boolean" required>
  `true` when the token was refreshed successfully.
</ResponseField>

<ResponseField name="Value" type="string | null">
  The new JWT access token string. Use this as the `Authorization: Bearer` value for subsequent API requests. `null` when `WasSuccessful` is `false`.
</ResponseField>

<ResponseField name="Status" type="number">
  HTTP-style status code mirrored in the response body. `200` on success, `500` on failure.
</ResponseField>

<ResponseField name="Message" type="string | null">
  Human-readable message. Usually `"OK"` on success.
</ResponseField>

<ResponseField name="Errors" type="any">
  Validation or server errors. `null` on success.
</ResponseField>

## Examples

### Refresh with default validity (30 minutes)

```http theme={null}
POST /api/sys/users/token/refresh
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{}
```

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

### Refresh with custom validity (60 minutes)

```http theme={null}
POST /api/sys/users/token/refresh
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "ValidityInMinutes": 60
}
```

```json theme={null}
{
  "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

<UrlParameter name="id" type="integer" required>
  The ID of the user whose token should be refreshed.
</UrlParameter>

### Request Body

Same as the current-user endpoint — optional `ValidityInMinutes`.

### Example

```http theme={null}
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:

```typescript theme={null}
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

<ResponseField name="401 Unauthorized" type="error">
  The bearer token is missing, expired, or invalid. The user must sign in again via `POST /api/token`.
</ResponseField>

<ResponseField name="AccessDenied" type="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.
</ResponseField>

## 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            |