Change the password of the account the bearer token belongs to.

PUT

/api/v1/auth/password

curl --request PUT \
  --url https://example.com/api/v1/auth/password \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "current_password": "example", "new_password": "example" }'

This ends the caller’s own session, on purpose (ADR-122 decision 3). revoke_user is the same primitive an administrator’s reset uses, so there is one answer to “a password changed — what happens to the tokens”, and signing in again is what proves the new password actually works.

The alternative (revoke everything, then mint a replacement) is not safe here: a signed session is denied when its iat is at or before the revocation cutoff, both are second-granularity, and issue reads the clock itself — so a replacement minted in the same second would be denied, and the caller could not tell that from a broken password.

Authorizations

• bearer

Request Body^required

Media typeapplication/json

Change-your-own-password request body. Neither field is logged, echoed, or audited.

object

current_password

required

The password the caller signs in with today. Required even though the caller already holds a valid session — without it, a stolen session is a stolen account.

string

new_password

required

What to replace it with. Same minimum length as an administrator’s reset.

string

Example^generated

{
  "current_password": "example",
  "new_password": "example"
}

Responses

204

Password changed; every session of this account — the caller’s own included — is revoked, so the client must sign in again

400

The new password is too short (weak_password), is the same as the current one (password_unchanged), or this account signs in through a directory or an identity provider and has no local password (not_a_local_account)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token, or current_password is wrong — one code for both

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

The session names an account that no longer exists

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

429

Too many attempts; Retry-After carries the wait in seconds

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

This core has no write side (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}