Consume a setup token and set a password.

POST

/auth/set-password

curl --request POST \
  --url https://example.com/auth/set-password \
  --header 'Content-Type: application/json' \
  --data '{ "password": "example", "setupToken": "example" }'

Authorizations

• None

Request Body^required

JSON body for POST /auth/set-password.

Media typeapplication/json

JSON body for POST /auth/set-password.

object

password

required

The new password to set.

string

setupToken

required

The one-time setup token (returned from principal creation or reset).

string

Example^generated

{
  "password": "example",
  "setupToken": "example"
}

Responses

200

Successful login response containing a JWT.

Media typeapplication/json

Successful login response containing a JWT.

object

expiresIn

required

Token lifetime in seconds.

integer format: int64

token

required

Signed JWT (ES256).

string

Example^generated

{
  "expiresIn": 1,
  "token": "example"
}

400

Failed to parse the request body as JSON

Media typetext/plain

string

415

Expected request with Content-Type: application/json

Media typetext/plain

string

422

Failed to deserialize the JSON body into the target type

Media typetext/plain

string

default

Structured error envelope (SPEC-DATA-0006): {"errors": [{"scope", "target", "code", "message"}, ...]}.

Media typeapplication/json

The top-level response body. Wraps a non-empty list of [ErrorEntry].

object

errors

required

The error entries making up the envelope. Always non-empty.

Array<object>

One entry in the error envelope.

Carries an anchoring [ErrorScope], an optional target that disambiguates within the scope, a stable SCREAMING_SNAKE_CASE code, and a human-readable English message. See SPEC-DATA-0006 for the full envelope contract.

object

code

required

Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.

string

location

Any of:

object

HFX source location for a [DataError::HfxCompileError] entry.

Emitted as the extra location field on the entry JSON when present, per SPEC-UI-0043. The line/column are 1-based. The frame is the offending source line extracted verbatim from the input.

object

column

required

1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.

integer format: uint32

frame

The offending source line text, when available.

string | null

line

required

1-based line number within the source text.

integer format: uint32

null

null

message

required

Server-authored English message. Not part of the API contract; may change across releases without notice.

string

rule

The key of the ValidationRule that failed, when the code is RULE_FAILED. None for all other codes.

Skipped during serialization when absent so it does not appear on unrelated entries (same pattern as location).

Documented here as a plain string (#[schemars(with = "...")]) rather than a $ref to ValidationRuleKey’s own schema: that type lives in metadata-types, which does not derive JsonSchema yet (tracked by #812). ValidationRuleKey serializes transparently as its inner string (serde’s default newtype-struct behavior), so this is an accurate wire-shape description, not a placeholder.

string | null

scope

required

Anchoring category. Drives client-side rendering.

One of:

string

Attached to a specific request field. target is the field key.

string

Allowed value: field

string

Attached to the record being written or read. target is the id if known.

string

Allowed value: record

string

Attached to the request as a whole. target is always null.

string

Allowed value: global

target

Field key for field scope, record id for record scope, null otherwise. Always serialized, even when null.

string | null

Example

{
  "errors": [
    {
      "scope": "field"
    }
  ]
}