post /change-password

Post change password

This endpoint allows a user to change its own password. Knowledge of the currently used (old) password is required; the user is identified by uniqueUserIdentifier rather than by the request’s bearer token.

The new password is available immediately after the request.

Already created tokens remain valid up to their expiration date, i.e. changing the password does not revoke existing tokens.

newPassword must be different from currentPassword, otherwise a 400 Bad Request is returned. The default anonymous user can not change its password and receives a 403 Forbidden response instead.

Request

curl \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "ActionChangePassword",
        "currentPassword": "1234",
        "newPassword": "9876",
        "uniqueUserIdentifier": "test@example.com"
      }' \
  https://api.example.com/change-password
import requests


url = "https://api.example.com/change-password"


payload = {
  "type": "ActionChangePassword",
  "currentPassword": "1234",
  "newPassword": "9876",
  "uniqueUserIdentifier": "test@example.com"
}
headers = {"Content-Type": "application/json"}


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


print(response.json())
const url = 'https://api.example.com/change-password';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"type":"ActionChangePassword","currentPassword":"1234","newPassword":"9876","uniqueUserIdentifier":"test@example.com"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.example.com/change-password', [
  'body' => '{"type": "ActionChangePassword", "currentPassword": "1234", "newPassword": "9876", "uniqueUserIdentifier": "test@example.com"}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Response

204 · No Content

Password was changed successfully.

MDN HTTP.dev 

400 · Bad Request

General issues with the user provided request, e.g. missing properties, malformed properties, failing validation logic etc.

MDN HTTP.dev 

400 · Bad Request

A provided property has the wrong type or fails a validation rule.

MDN HTTP.dev 

401 · Unauthorized

The provided token is either invalid or expired.

MDN HTTP.dev 

403 · Forbidden

The identified user is the default anonymous user, which can not change its password.

MDN HTTP.dev 

response has no body

Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API

no schema available

{
  "type": "https://api.example.com/error/400/missing-property",
  "title": "Missing property",
  "status": 400,
  "detail": "Endpoint requires that the request contains property 'type' to be set to a valid type."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
{
  "type": "https://api.example.com/error/400/bad-content",
  "title": "Bad content",
  "status": 400,
  "detail": "Endpoint expects property 'newPassword' to be password which is not identical to the old password, got string '<redacted>'."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
{
  "type": "https://api.example.com/error/401/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization for the request failed due to possible problems with the token (incorrect or expired), password (incorrect or changed), the user's unique identifier, or the user's status (e.g., missing, blocked, or deleted)."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
{
  "type": "https://api.example.com/error/403/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Requested endpoint, element or action is forbidden."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}

Request Header

Authorization

optional

Bearer token for user authentication. If omitted, the request is processed as an anonymous user; if provided, the associated user account is used.

MDN HTTP.dev Authentication guide 

Request Body

{
  "type": "ActionChangePassword",
  "currentPassword": "1234",
  "newPassword": "9876",
  "uniqueUserIdentifier": "test@example.com"
}
{
  "type": "object",
  "required": [
    "type",
    "currentPassword",
    "newPassword",
    "uniqueUserIdentifier"
  ],
  "properties": {
    "type": {
      "type": "string",
      "description": "Must be `ActionChangePassword`. No other values are currently possible.",
      "enum": [
        "ActionChangePassword"
      ],
      "example": "ActionChangePassword"
    },
    "currentPassword": {
      "type": "string",
      "description": "The user's currently used password, in plain text.",
      "example": "1234"
    },
    "newPassword": {
      "type": "string",
      "description": "The user's new password, in plain text. Must be different from `currentPassword`. Any string is accepted and is hashed internally; no password complexity check is performed.",
      "example": "9876"
    },
    "uniqueUserIdentifier": {
      "type": "string",
      "description": "Some attribute uniquely identifying a user, normally an email address. The property name used to store it can be configured server-side.",
      "example": "test@example.com"
    }
  }
}

Response Header

Access-Control-Allow-Headers

always

Specifies which HTTP headers can be used during a cross-origin request, returned in preflight responses.

MDN HTTP.dev 

Access-Control-Allow-Methods

always

Indicates which HTTP methods are permitted for cross-origin requests, typically returned in preflight responses.

MDN HTTP.dev 

Access-Control-Allow-Origin

always

Specifies which origin(s) may access the resource.

MDN HTTP.dev 

Access-Control-Expose-Headers

always

Lists the response headers that browsers are allowed to access from JavaScript beyond the default restricted set.

MDN HTTP.dev 

Allow

always

Lists the HTTP methods supported by the endpoint; returned alongside a 405 Method Not Allowed response.

MDN HTTP.dev 

Cache-Control

always

Directives controlling caching behavior for the response.

MDN HTTP.dev 

X-Powered-By

always

Identifies the underlying API implementation.

MDN HTTP.dev