Redeem a one-time code: sign this browser in, or ask it to confirm first.

POST

/v1/auth/session/redeem

curl --request POST \
  --url https://example.com/v1/auth/session/redeem \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example", "confirm": false, "returnTo": "example" }'

Authorizations

• None

Request Body^required

Body of POST /auth/session/redeem.

Media typeapplication/json

Body of POST /auth/session/redeem.

object

code

required

The one-time code from POST /auth/session.

string

confirm

The user confirmed signing in as the code’s principal. Without it the redeem answers 409 CONFIRMATION_REQUIRED unless the browser proves it is already signed in as that principal.

boolean

returnTo

required

Canonical name of the surface to sign in to (henceforth:app, acme.crm:app). Required: there is no default surface. A mount path is refused, and so is a missing or null value (400 INVALID_RETURN_TO).

string

Responses

200

Success body of POST /auth/session/redeem.

Media typeapplication/json

Success body of POST /auth/session/redeem.

object

expiresIn

required

Lifetime of both tokens in seconds, capped at the minting token’s.

integer format: int64

loginToken

required

Unscoped token for the /login/ slot.

string

mountPath

required

Where the page stores the token and navigates: the registry’s mount path for name, never input.

string

name

required

Canonical name of the surface the scoped token was issued to.

string

surfaceToken

required

Token stamped for the surface; goes in the surface’s browser slot.

string

Example^generated

{
  "expiresIn": 1,
  "loginToken": "example",
  "mountPath": "example",
  "name": "example",
  "surfaceToken": "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": [{"domain", "scope", "target", "code", "message"}, ...]}. domain (added #950 D9) names the subsystem that produced the entry (data, metadata, apply, git, auth, iam, hfx, or api for a transport-level failure with no domain error behind it) and is always present.

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 a [Domain] naming the subsystem that produced it, 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

domain

required

Which subsystem produced this entry. Always serialized.

One of:

string

data::error::DataError – record CRUD, validation, queries.

string

Allowed value: data

string

server::routes::metadata::error::MetadataError – the metadata write API (module/object/field/screen PUT and POST).

string

Allowed value: metadata

string

server::apply::ApplyError – the metadata apply/plan pipeline.

string

Allowed value: apply

string

server::git::GitError – the git-backed metadata repository.

string

Allowed value: git

string

auth::error::AuthError – JWT and credential authentication.

string

Allowed value: auth

string

server::routes::iam::error::IamError – principal and credential management (IAM handlers still emit Domain::Data for genuine request-body field validation, which stays DataError).

string

Allowed value: iam

string

server::routes::hfx::error::HfxError – HFX parse/emit.

string

Allowed value: hfx

string

Module packages (.hfmod, #1165): package format, signature and compatibility refusals, and the install lifecycle that consumes them.

string

Allowed value: module

string

A transport-level ApiError built directly (forbidden, not_found, internal, service_unavailable), with no <Domain>Error behind it.

string

Allowed value: api

location

Any of:

object

HFX source location for an HFX_PARSE entry.

Emitted as the extra location field on the entry JSON when present. 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 validation rule 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).

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": [
    {
      "domain": "data",
      "scope": "field"
    }
  ]
}