Auth Api Change Password

Auth Api Change Password
Self-service password change

Changes the caller's own password (LOCAL accounts only) and clears mustChangePassword. A voluntary change keeps the current session and revokes every other active session of the user. A mandatory change (mustChangePassword was true) also revokes the current session and clears its cookie, and the body says reauthenticationRequired: true, so the client signs in again with the new password. While mustChangePassword is true this is one of the only operations allowed (with session and logout); all others answer 403 PASSWORD_CHANGE_REQUIRED. Five wrong current passwords within 15 minutes block further changes of that account until the window ends. Accessible to every authenticated role.

Request
URI
POST
https://{api_host}/api/v1/auth/change-password
COPY
Request Body

The caller's current password and the new password, which must satisfy the password policy and differ from the current one. There is no confirmation field.

ChangePasswordRequest of type(s) application/json
Required  

Show optional properties

{
    "currentPassword": "string",
    "newPassword": "string"
}
{
    "currentPassword": "<redacted>",
    "newPassword": "Exampl3-Passw0rd!"
}
string As password As password
currentPassword
Required  

The caller's current password. A wrong value is answered with 401 INVALID_CREDENTIALS.

string As password As ^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&+=(){}_-])(?=\S+$).{8,20}$
newPassword
Required  
Constraints: minLength: 8 maxLength: 20

8-20 characters with at least one digit, one lowercase letter, one uppercase letter and one special character from !@#$%^&+=(){}_-, and no whitespace. A value that fails the policy is answered with 400 INVALID_PASSWORD_FORMAT.

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK; the password was changed. reauthenticationRequired says whether the current session was ended

Returns ChangePasswordResponse of type(s) application/json
{
    "reauthenticationRequired": true
}
boolean
reauthenticationRequired
Required  

True after a mandatory change: the current session was revoked and the client must sign in again. False after a voluntary change, which keeps the current session.

Response Headers

string
Cache-Control

no-store

string
Set-Cookie

Clears VTP_SESSION (Max-Age=0) after a mandatory change


400

400 Bad Request: INVALID_PASSWORD_FORMAT when newPassword fails the password policy, PASSWORD_REUSE when it equals the current password, or MALFORMED_REQUEST

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED without a session, or INVALID_CREDENTIALS when currentPassword is wrong

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead)

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: USER_NOT_FOUND

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: PASSWORD_MANAGED_EXTERNALLY for an SSO account, whose password the identity provider manages

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


429

429 Too Many Requests: TOO_MANY_PASSWORD_ATTEMPTS with a Retry-After header in seconds after repeated wrong current passwords, or the gateway rate limit (a plain response with no JSON body)

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.

Response Headers

integer
Retry-After

Seconds until the account may try again (absent on the gateway response)


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"currentPassword":"string","newPassword":"string"}' https://{api_host}/api/v1/auth/change-password