Auth

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Sign-in, sessions, passkeys, TOTP and the operator's elevation.

Back to the web API reference.

POST /api/auth/login

Validates the operator token (throttled, constant-time) and issues a hashed session cookie.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: LoginRequest

  • tokenstringrequiredOperator token from the client; compared in constant time and never persisted.

Responses

  • 200Signed in; the response sets the operator session cookie. Body: LoginResponse (application/json)3 fields
    • okbooleanrequiredAlways true on this success path.
    • rolestringrequiredIssued role (operator for token login).
    • default_viewstringrequiredPost-login SPA landing view from operator preferences (discover on lookup failure).
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The token is wrong (unauthorized). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403An Owner exists, so operator sign-in is off (operator_login_disabled); sign in as a user. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many attempts from this client; retry after Retry-After seconds. Body: LoginThrottled (application/json)4 fields
    • errorstringrequiredAlways too_many_requests.
    • messagestringrequiredCaller-facing explanation naming the wait.
    • statusinteger (int32)requiredAlways 429 (duplicates the response status for clients). At least 0.
    • retry_after_secsinteger (int64)requiredSeconds until this client may try again; the same value as Retry-After. At least 0.
  • 500The library could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/login' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"token": "9b1e4f6a2c8d3e5f7a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/login' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"token": "9b1e4f6a2c8d3e5f7a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/login",
    json={"token": "9b1e4f6a2c8d3e5f7a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"token": "9b1e4f6a2c8d3e5f7a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/login")
    .json(&serde_json::json!({"token": "9b1e4f6a2c8d3e5f7a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Signed in; the response sets the operator session cookie.

{
  "ok": true,
  "role": "operator",
  "default_view": "discover"
}

Schema:

{
  "type": "object",
  "description": "JSON body after a successful operator token login.",
  "required": [
    "ok",
    "role",
    "default_view"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "role": {
      "type": "string",
      "description": "Issued role (`operator` for token login).",
      "example": "operator"
    },
    "default_view": {
      "type": "string",
      "description": "Post-login SPA landing view from operator preferences (`discover` on lookup failure).",
      "example": "discover"
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The token is wrong (unauthorized).

{
  "error": "unauthorized",
  "message": "Invalid operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 403: An Owner exists, so operator sign-in is off (operator_login_disabled); sign in as a user.

{
  "error": "operator_login_disabled",
  "message": "Operator token sign-in is unavailable after an Owner account exists. Open Bookclerk from the system tray, or elevate from an Owner session.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `token` at line 1 column 2

Schema:

A text/plain body: a string.

Status 429: Too many attempts from this client; retry after Retry-After seconds.

{
  "error": "too_many_requests",
  "message": "Too many failed login attempts. Try again in 45 seconds.",
  "retry_after_secs": 45,
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "JSON body of a 429 after too many failed sign-in attempts from one client.",
  "required": [
    "error",
    "message",
    "status",
    "retry_after_secs"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `too_many_requests`.",
      "example": "too_many_requests"
    },
    "message": {
      "type": "string",
      "description": "Caller-facing explanation naming the wait.",
      "example": "Too many failed login attempts. Try again in 45 seconds."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Always 429 (duplicates the response status for clients).",
      "example": 429,
      "minimum": 0
    },
    "retry_after_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until this client may try again; the same value as `Retry-After`.",
      "example": 45,
      "minimum": 0
    }
  }
}

Status 500: The library could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/signin

Public sign-in picker: operator-token availability, SSO IdPs, integration logins.

Errors

Returns 500 when the owner-count query fails.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 200The sign-in methods this library offers. Body: SigninMethods (application/json)4 fields
    • operator_tokenbooleanrequiredWhether the operator token may be entered in the SPA (only before an Owner exists).
    • oidcarray of SigninOidcProviderrequiredEnabled OIDC identity providers, in configuration order.
    • integrationsarray of SigninIntegrationrequiredIntegrations that accept their own credentials at sign-in.
    • require_second_factorbooleanrequiredWhether daemon.auth.require_second_factor is on, so clients can explain the enrollment step.
  • 500The library could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/signin'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/signin'
import requests

response = requests.get("http://127.0.0.1:8787/api/auth/signin")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/signin");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/auth/signin").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The sign-in methods this library offers.

{
  "operator_token": false,
  "oidc": [
    {
      "id": "google",
      "name": "Google",
      "preset": "google"
    }
  ],
  "integrations": [
    {
      "id": "audiobookshelf",
      "name": "Audiobookshelf"
    }
  ],
  "require_second_factor": false
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/signin`: the ways this library lets people sign in.",
  "required": [
    "operator_token",
    "oidc",
    "integrations",
    "require_second_factor"
  ],
  "properties": {
    "operator_token": {
      "type": "boolean",
      "description": "Whether the operator token may be entered in the SPA (only before an Owner exists).",
      "example": false
    },
    "oidc": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One OIDC identity provider offered on the sign-in page.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Provider id from `[auth.oidc.providers]`, used in `/api/auth/oidc/{id}/start`.",
            "example": "google"
          },
          "name": {
            "type": "string",
            "description": "Button label.",
            "example": "Google"
          },
          "preset": {
            "type": [
              "string",
              "null"
            ],
            "description": "Known social preset the client may style (`google`, `github`, …), when the provider matches one.",
            "example": "google"
          }
        }
      },
      "description": "Enabled OIDC identity providers, in configuration order."
    },
    "integrations": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One integration that signs people in with its own credentials.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Integration id, used in `/api/integrations/{id}/login`.",
            "example": "audiobookshelf"
          },
          "name": {
            "type": "string",
            "description": "Button label.",
            "example": "Audiobookshelf"
          }
        }
      },
      "description": "Integrations that accept their own credentials at sign-in."
    },
    "require_second_factor": {
      "type": "boolean",
      "description": "Whether `daemon.auth.require_second_factor` is on, so clients can explain the enrollment step.",
      "example": false
    }
  }
}

Status 500: The library could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/tray-handoff/prepare

Mint a single-use tray Open Bookclerk ticket (Bearer, direct loopback only).

Returns a cryptographically random code and its lifetime. The durable operator token stays in Authorization. Each call replaces any unused ticket. The code is registered for log redaction (including percent-encoded form). Lifetime comes from live [daemon.auth] tray_handoff_ttl_secs (default 180, clamped to 30..=900).

Errors

Returns 403 when the request is not a direct loopback call, 401 when Bearer does not match, or 429 when this client is locked out.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: operatorToken

Responses

  • 200A single-use tray ticket. Body: TrayHandoffPrepareResponse (application/json)2 fields
    • codestringrequiredSingle-use loopback handoff code for GET /api/auth/tray-handoff?code=.
    • expires_in_secsinteger (int64)requiredSeconds until this ticket expires (matches the in-process deadline). At least 0.
  • 204Operator authentication is off, so no ticket is needed. No body.
  • 401The Bearer token is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The request did not come straight from loopback. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 429Too many failed attempts from this client; retry after Retry-After seconds. Body: LoginThrottled (application/json)4 fields
    • errorstringrequiredAlways too_many_requests.
    • messagestringrequiredCaller-facing explanation naming the wait.
    • statusinteger (int32)requiredAlways 429 (duplicates the response status for clients). At least 0.
    • retry_after_secsinteger (int64)requiredSeconds until this client may try again; the same value as Retry-After. At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/tray-handoff/prepare' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/tray-handoff/prepare' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/tray-handoff/prepare",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/tray-handoff/prepare", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/tray-handoff/prepare")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: A single-use tray ticket.

{
  "code": "9b4f1c2e-3d5a-4b6c-8e7f-0a1b2c3d4e5f",
  "expires_in_secs": 180
}

Schema:

{
  "type": "object",
  "description": "JSON returned to the tray after a successful prepare.",
  "required": [
    "code",
    "expires_in_secs"
  ],
  "properties": {
    "code": {
      "type": "string",
      "description": "Single-use loopback handoff code for `GET /api/auth/tray-handoff?code=`.",
      "example": "9b4f1c2e-3d5a-4b6c-8e7f-0a1b2c3d4e5f"
    },
    "expires_in_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until this ticket expires (matches the in-process deadline).",
      "example": 180,
      "minimum": 0
    }
  }
}

Status 204: Operator authentication is off, so no ticket is needed. No body.

Status 401: The Bearer token is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The request did not come straight from loopback.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 429: Too many failed attempts from this client; retry after Retry-After seconds.

{
  "error": "too_many_requests",
  "message": "Too many failed login attempts. Try again in 45 seconds.",
  "retry_after_secs": 45,
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "JSON body of a 429 after too many failed sign-in attempts from one client.",
  "required": [
    "error",
    "message",
    "status",
    "retry_after_secs"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `too_many_requests`.",
      "example": "too_many_requests"
    },
    "message": {
      "type": "string",
      "description": "Caller-facing explanation naming the wait.",
      "example": "Too many failed login attempts. Try again in 45 seconds."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Always 429 (duplicates the response status for clients).",
      "example": 429,
      "minimum": 0
    },
    "retry_after_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until this client may try again; the same value as `Retry-After`.",
      "example": 45,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/tray-handoff

Consume the pending tray ticket and set a localhost operator session cookie.

Direct loopback only (TCP peer, localhost Host, no forwarded headers). Requires the one-time code from prepare; ?token= is ignored and cannot mint a session. Wrong or missing codes do not consume the slot.

Errors

Returns 403 when the request is not a direct loopback call or the code does not match a still-valid ticket.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • codequerystringPresented handoff code; missing or empty fails closed without consuming the slot.

Responses

  • 307Redirects into the app with a localhost operator session. No body.
  • 403The ticket is missing, used or not from loopback. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/tray-handoff'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/tray-handoff'
import requests

response = requests.get("http://127.0.0.1:8787/api/auth/tray-handoff")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/tray-handoff");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/auth/tray-handoff").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 307: Redirects into the app with a localhost operator session. No body.

Status 403: The ticket is missing, used or not from loopback.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/me

Resolves the caller and returns /me JSON; unauthenticated callers get 401.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: operatorToken or operatorSession or portalSession

Responses

  • 200Who the caller is (operator, portal user, or impersonation). Body: AuthMeResponse (application/json)11 fields
    • authenticatedbooleanrequiredWhether the request resolved to an operator, portal, or impersonated session.
    • rolestring or nulloperator, owner, administrator, or member (legacy clients may still send portal).
    • default_viewstringrequiredConfigured post-auth landing view (discover / library / accounts / wishlist). Loaded from per-user DB preferences (not config.toml).
    • can_acquirebooleanrequiredWhether this session may acquire / scan / manage jobs. True for operator and administrator.
    • elevatedbooleanrequiredTrue when this operator session was created via Owner elevate.
    • administers_nodesbooleanrequiredWhether this session reaches the node administration routes and the library Status page: the operator, an Owner or Administrator, or a Member who owns at least one node (a branch they linked).
    • impersonatingAuthMeImpersonating or nullPresent when the operator is impersonating a User.
    • portalPortalMeInfo or nullLinked portal identity when the caller is a portal (or impersonated) user.
    • userAuthMeUser or nullFirst-party user when the session is linked to a users row.
    • second_factorAuthSecondFactor or nullPassword-login second-factor policy and this user's enrollment.
    • see_pricesbooleanrequiredWhether the caller's "See prices and store links" member control allows prices and store links. The library already drops them from its answers when it does not; the app uses this to show no store links of its own either. Always true for the operator.
  • 401Nobody is signed in: the same body with authenticated false, so the app can show the sign-in screen. Body: AuthMeResponse (application/json)11 fields
    • authenticatedbooleanrequiredWhether the request resolved to an operator, portal, or impersonated session.
    • rolestring or nulloperator, owner, administrator, or member (legacy clients may still send portal).
    • default_viewstringrequiredConfigured post-auth landing view (discover / library / accounts / wishlist). Loaded from per-user DB preferences (not config.toml).
    • can_acquirebooleanrequiredWhether this session may acquire / scan / manage jobs. True for operator and administrator.
    • elevatedbooleanrequiredTrue when this operator session was created via Owner elevate.
    • administers_nodesbooleanrequiredWhether this session reaches the node administration routes and the library Status page: the operator, an Owner or Administrator, or a Member who owns at least one node (a branch they linked).
    • impersonatingAuthMeImpersonating or nullPresent when the operator is impersonating a User.
    • portalPortalMeInfo or nullLinked portal identity when the caller is a portal (or impersonated) user.
    • userAuthMeUser or nullFirst-party user when the session is linked to a users row.
    • second_factorAuthSecondFactor or nullPassword-login second-factor policy and this user's enrollment.
    • see_pricesbooleanrequiredWhether the caller's "See prices and store links" member control allows prices and store links. The library already drops them from its answers when it does not; the app uses this to show no store links of its own either. Always true for the operator.
  • 503The portal session could not be checked because the library did not answer in time. The response carries Retry-After; ask again rather than showing the sign-in screen. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/me' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/me' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/me",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/me", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/me")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Who the caller is (operator, portal user, or impersonation).

{
  "authenticated": true,
  "role": "administrator",
  "default_view": "library",
  "can_acquire": true,
  "elevated": false,
  "administers_nodes": false,
  "impersonating": {
    "user_id": 7,
    "display_name": "Sam"
  },
  "portal": {
    "identity_id": 3,
    "provider": "local",
    "external_user_id": "7",
    "label": "Sam"
  },
  "user": {
    "id": 7,
    "role": "administrator",
    "display_name": "Sam",
    "email": "sam@example.com",
    "has_password": true,
    "has_avatar": false,
    "avatar_source": "auto",
    "gravatar_hash": "0bc83cb571cd1c50ba6f3e8a78ef1346b6b31bd4d35b8d3dc1f0c8a3b4a9f7e2",
    "sso_pictures": [
      {
        "identity_id": 3,
        "provider": "oidc:google",
        "picture_url": "https://lh3.googleusercontent.com/a/example=s96-c",
        "picture_path": "/api/images/aHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EvZXhhbXBsZT1zOTYtYw.N14rqh66Bok9-eCqJKBNoQ",
        "last_used_at": "2026-10-29T08:15:00Z"
      }
    ]
  },
  "second_factor": {
    "required": false,
    "totp": true,
    "passkey_count": 1,
    "enrolled": true
  },
  "see_prices": true
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/me`.",
  "required": [
    "authenticated",
    "default_view",
    "can_acquire",
    "elevated",
    "administers_nodes",
    "see_prices"
  ],
  "properties": {
    "authenticated": {
      "type": "boolean",
      "description": "Whether the request resolved to an operator, portal, or impersonated session.",
      "example": true
    },
    "role": {
      "type": [
        "string",
        "null"
      ],
      "description": "`operator`, `owner`, `administrator`, or `member` (legacy clients may\nstill send `portal`).",
      "example": "administrator"
    },
    "default_view": {
      "type": "string",
      "description": "Configured post-auth landing view (`discover` / `library` / `accounts` /\n`wishlist`).\nLoaded from per-user DB preferences (not config.toml).",
      "example": "library"
    },
    "can_acquire": {
      "type": "boolean",
      "description": "Whether this session may acquire / scan / manage jobs.\nTrue for operator and administrator.",
      "example": true
    },
    "elevated": {
      "type": "boolean",
      "description": "True when this operator session was created via Owner elevate.",
      "example": false
    },
    "administers_nodes": {
      "type": "boolean",
      "description": "Whether this session reaches the node administration routes and the\nlibrary Status page: the operator, an Owner or Administrator, or a\nMember who owns at least one node (a branch they linked).",
      "example": false
    },
    "impersonating": {
      "oneOf": [
        {
          "type": "object",
          "description": "Present when the operator is impersonating a User.",
          "required": [
            "user_id"
          ],
          "properties": {
            "user_id": {
              "type": "integer",
              "format": "int64",
              "description": "First-party `users.id` being impersonated.",
              "example": 7
            },
            "display_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Display name of the impersonated user when the row exists.",
              "example": "Sam"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "portal": {
      "oneOf": [
        {
          "type": "object",
          "description": "Linked portal identity when the caller is a portal (or impersonated) user.",
          "required": [
            "identity_id",
            "provider",
            "external_user_id"
          ],
          "properties": {
            "identity_id": {
              "type": "integer",
              "format": "int64",
              "description": "`portal_identities.id` for this session.",
              "example": 3
            },
            "provider": {
              "type": "string",
              "description": "Identity-broker id (`local`, OIDC provider name, …).",
              "example": "local"
            },
            "external_user_id": {
              "type": "string",
              "description": "Provider-stable subject / external user id.",
              "example": "7"
            },
            "label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional operator-facing label for the identity.",
              "example": "Sam"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "user": {
      "oneOf": [
        {
          "type": "object",
          "description": "First-party user when the session is linked to a `users` row.",
          "required": [
            "id",
            "role",
            "has_password",
            "has_avatar",
            "avatar_source"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "First-party `users.id`.",
              "example": 7
            },
            "role": {
              "type": "string",
              "description": "Role string (`owner`, `administrator`, `member`).",
              "example": "administrator"
            },
            "display_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional human-readable name from the user row.",
              "example": "Sam"
            },
            "email": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional email; omitted from JSON when unset.",
              "example": "sam@example.com"
            },
            "has_password": {
              "type": "boolean",
              "description": "True when a local password hash is stored (invite users may be false).",
              "example": true
            },
            "has_avatar": {
              "type": "boolean",
              "description": "True when a JPEG avatar is stored under `files_dir/avatars/{id}.*`.",
              "example": false
            },
            "avatar_source": {
              "type": "string",
              "description": "Selected picture source (`auto`, `monogram`, `gravatar`, `upload`, `sso:{id}`).",
              "example": "auto"
            },
            "gravatar_hash": {
              "type": [
                "string",
                "null"
              ],
              "description": "SHA-256 hex of the contact email for Gravatar, when an email is set.",
              "example": "0bc83cb571cd1c50ba6f3e8a78ef1346b6b31bd4d35b8d3dc1f0c8a3b4a9f7e2"
            },
            "sso_pictures": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "HTTPS picture from a linked identity provider.",
                "required": [
                  "identity_id",
                  "provider",
                  "picture_url"
                ],
                "properties": {
                  "identity_id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "`portal_identities.id`.",
                    "example": 3
                  },
                  "provider": {
                    "type": "string",
                    "description": "Identity-broker id (`oidc:google`, …).",
                    "example": "oidc:google"
                  },
                  "picture_url": {
                    "type": "string",
                    "description": "HTTPS URL to display.",
                    "example": "https://lh3.googleusercontent.com/a/example=s96-c"
                  },
                  "picture_path": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Same-origin 128 px copy of `picture_url` for the web app to show,\nwhen this node can sign it.",
                    "example": "/api/images/aHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EvZXhhbXBsZT1zOTYtYw.N14rqh66Bok9-eCqJKBNoQ"
                  },
                  "last_used_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 last portal-session activity for this identity, when any.",
                    "example": "2026-10-29T08:15:00Z"
                  }
                }
              },
              "description": "IdP-supplied pictures the user can pick."
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "second_factor": {
      "oneOf": [
        {
          "type": "object",
          "description": "Password-login second-factor policy and this user's enrollment.",
          "required": [
            "required",
            "totp",
            "passkey_count",
            "enrolled"
          ],
          "properties": {
            "required": {
              "type": "boolean",
              "description": "`daemon.auth.require_second_factor`.",
              "example": false
            },
            "totp": {
              "type": "boolean",
              "description": "Confirmed authenticator-app TOTP.",
              "example": true
            },
            "passkey_count": {
              "type": "integer",
              "format": "int64",
              "description": "Number of registered passkeys.",
              "example": 1,
              "minimum": 0
            },
            "enrolled": {
              "type": "boolean",
              "description": "True when TOTP is enabled or at least one passkey exists.",
              "example": true
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "see_prices": {
      "type": "boolean",
      "description": "Whether the caller's \"See prices and store links\" member control\nallows prices and store links. The library already drops them from\nits answers when it does not; the app uses this to show no store\nlinks of its own either. Always true for the operator.",
      "example": true
    }
  }
}

Status 401: Nobody is signed in: the same body with authenticated false, so the app can show the sign-in screen.

{
  "administers_nodes": false,
  "authenticated": false,
  "can_acquire": false,
  "default_view": "discover",
  "elevated": false,
  "see_prices": false
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/me`.",
  "required": [
    "authenticated",
    "default_view",
    "can_acquire",
    "elevated",
    "administers_nodes",
    "see_prices"
  ],
  "properties": {
    "authenticated": {
      "type": "boolean",
      "description": "Whether the request resolved to an operator, portal, or impersonated session.",
      "example": true
    },
    "role": {
      "type": [
        "string",
        "null"
      ],
      "description": "`operator`, `owner`, `administrator`, or `member` (legacy clients may\nstill send `portal`).",
      "example": "administrator"
    },
    "default_view": {
      "type": "string",
      "description": "Configured post-auth landing view (`discover` / `library` / `accounts` /\n`wishlist`).\nLoaded from per-user DB preferences (not config.toml).",
      "example": "library"
    },
    "can_acquire": {
      "type": "boolean",
      "description": "Whether this session may acquire / scan / manage jobs.\nTrue for operator and administrator.",
      "example": true
    },
    "elevated": {
      "type": "boolean",
      "description": "True when this operator session was created via Owner elevate.",
      "example": false
    },
    "administers_nodes": {
      "type": "boolean",
      "description": "Whether this session reaches the node administration routes and the\nlibrary Status page: the operator, an Owner or Administrator, or a\nMember who owns at least one node (a branch they linked).",
      "example": false
    },
    "impersonating": {
      "oneOf": [
        {
          "type": "object",
          "description": "Present when the operator is impersonating a User.",
          "required": [
            "user_id"
          ],
          "properties": {
            "user_id": {
              "type": "integer",
              "format": "int64",
              "description": "First-party `users.id` being impersonated.",
              "example": 7
            },
            "display_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Display name of the impersonated user when the row exists.",
              "example": "Sam"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "portal": {
      "oneOf": [
        {
          "type": "object",
          "description": "Linked portal identity when the caller is a portal (or impersonated) user.",
          "required": [
            "identity_id",
            "provider",
            "external_user_id"
          ],
          "properties": {
            "identity_id": {
              "type": "integer",
              "format": "int64",
              "description": "`portal_identities.id` for this session.",
              "example": 3
            },
            "provider": {
              "type": "string",
              "description": "Identity-broker id (`local`, OIDC provider name, …).",
              "example": "local"
            },
            "external_user_id": {
              "type": "string",
              "description": "Provider-stable subject / external user id.",
              "example": "7"
            },
            "label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional operator-facing label for the identity.",
              "example": "Sam"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "user": {
      "oneOf": [
        {
          "type": "object",
          "description": "First-party user when the session is linked to a `users` row.",
          "required": [
            "id",
            "role",
            "has_password",
            "has_avatar",
            "avatar_source"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "First-party `users.id`.",
              "example": 7
            },
            "role": {
              "type": "string",
              "description": "Role string (`owner`, `administrator`, `member`).",
              "example": "administrator"
            },
            "display_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional human-readable name from the user row.",
              "example": "Sam"
            },
            "email": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional email; omitted from JSON when unset.",
              "example": "sam@example.com"
            },
            "has_password": {
              "type": "boolean",
              "description": "True when a local password hash is stored (invite users may be false).",
              "example": true
            },
            "has_avatar": {
              "type": "boolean",
              "description": "True when a JPEG avatar is stored under `files_dir/avatars/{id}.*`.",
              "example": false
            },
            "avatar_source": {
              "type": "string",
              "description": "Selected picture source (`auto`, `monogram`, `gravatar`, `upload`, `sso:{id}`).",
              "example": "auto"
            },
            "gravatar_hash": {
              "type": [
                "string",
                "null"
              ],
              "description": "SHA-256 hex of the contact email for Gravatar, when an email is set.",
              "example": "0bc83cb571cd1c50ba6f3e8a78ef1346b6b31bd4d35b8d3dc1f0c8a3b4a9f7e2"
            },
            "sso_pictures": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "HTTPS picture from a linked identity provider.",
                "required": [
                  "identity_id",
                  "provider",
                  "picture_url"
                ],
                "properties": {
                  "identity_id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "`portal_identities.id`.",
                    "example": 3
                  },
                  "provider": {
                    "type": "string",
                    "description": "Identity-broker id (`oidc:google`, …).",
                    "example": "oidc:google"
                  },
                  "picture_url": {
                    "type": "string",
                    "description": "HTTPS URL to display.",
                    "example": "https://lh3.googleusercontent.com/a/example=s96-c"
                  },
                  "picture_path": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Same-origin 128 px copy of `picture_url` for the web app to show,\nwhen this node can sign it.",
                    "example": "/api/images/aHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EvZXhhbXBsZT1zOTYtYw.N14rqh66Bok9-eCqJKBNoQ"
                  },
                  "last_used_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 last portal-session activity for this identity, when any.",
                    "example": "2026-10-29T08:15:00Z"
                  }
                }
              },
              "description": "IdP-supplied pictures the user can pick."
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "second_factor": {
      "oneOf": [
        {
          "type": "object",
          "description": "Password-login second-factor policy and this user's enrollment.",
          "required": [
            "required",
            "totp",
            "passkey_count",
            "enrolled"
          ],
          "properties": {
            "required": {
              "type": "boolean",
              "description": "`daemon.auth.require_second_factor`.",
              "example": false
            },
            "totp": {
              "type": "boolean",
              "description": "Confirmed authenticator-app TOTP.",
              "example": true
            },
            "passkey_count": {
              "type": "integer",
              "format": "int64",
              "description": "Number of registered passkeys.",
              "example": 1,
              "minimum": 0
            },
            "enrolled": {
              "type": "boolean",
              "description": "True when TOTP is enabled or at least one passkey exists.",
              "example": true
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "see_prices": {
      "type": "boolean",
      "description": "Whether the caller's \"See prices and store links\" member control\nallows prices and store links. The library already drops them from\nits answers when it does not; the app uses this to show no store\nlinks of its own either. Always true for the operator.",
      "example": true
    }
  }
}

Status 503: The portal session could not be checked because the library did not answer in time. The response carries Retry-After; ask again rather than showing the sign-in screen.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/elevate

Owner portal session + password re-auth → short-lived elevated operator cookie.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: operatorToken or operatorSession or portalSession

Request body

application/json: ElevateRequest

  • passwordstringrequiredOwner account password (re-authentication).

Responses

  • 200Elevated; the response sets a short-lived operator cookie. Body: Elevated (application/json)3 fields
    • okbooleanrequiredAlways true on this success path.
    • elevatedbooleanrequiredAlways true: the cookie the response sets is an elevated operator session.
    • expires_in_secsinteger (int64)requiredSeconds until the elevated session expires. At least 0.
  • 400Operator auth is off, or the password is empty. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401No portal session is signed in, or the password is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not an Owner, or the Owner has no password to check. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409The caller is already an operator. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many wrong passwords from this client or for this Owner; retry after Retry-After seconds. Body: LoginThrottled (application/json)4 fields
    • errorstringrequiredAlways too_many_requests.
    • messagestringrequiredCaller-facing explanation naming the wait.
    • statusinteger (int32)requiredAlways 429 (duplicates the response status for clients). At least 0.
    • retry_after_secsinteger (int64)requiredSeconds until this client may try again; the same value as Retry-After. At least 0.
  • 500The password hash could not be read, or the elevated session could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/elevate' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"password": "correct horse battery staple"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/elevate' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"password": "correct horse battery staple"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/elevate",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"password": "correct horse battery staple"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/elevate", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"password": "correct horse battery staple"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/elevate")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"password": "correct horse battery staple"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Elevated; the response sets a short-lived operator cookie.

{
  "ok": true,
  "elevated": true,
  "expires_in_secs": 900
}

Schema:

{
  "type": "object",
  "description": "JSON body after a successful Owner elevation.",
  "required": [
    "ok",
    "elevated",
    "expires_in_secs"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "elevated": {
      "type": "boolean",
      "description": "Always `true`: the cookie the response sets is an elevated operator session.",
      "example": true
    },
    "expires_in_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until the elevated session expires.",
      "example": 900,
      "minimum": 0
    }
  }
}

Status 400: Operator auth is off, or the password is empty. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: No portal session is signed in, or the password is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is not an Owner, or the Owner has no password to check. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 409: The caller is already an operator.

{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `password` at line 1 column 2

Schema:

A text/plain body: a string.

Status 429: Too many wrong passwords from this client or for this Owner; retry after Retry-After seconds.

{
  "error": "too_many_requests",
  "message": "Too many failed login attempts. Try again in 45 seconds.",
  "retry_after_secs": 45,
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "JSON body of a 429 after too many failed sign-in attempts from one client.",
  "required": [
    "error",
    "message",
    "status",
    "retry_after_secs"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `too_many_requests`.",
      "example": "too_many_requests"
    },
    "message": {
      "type": "string",
      "description": "Caller-facing explanation naming the wait.",
      "example": "Too many failed login attempts. Try again in 45 seconds."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Always 429 (duplicates the response status for clients).",
      "example": 429,
      "minimum": 0
    },
    "retry_after_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until this client may try again; the same value as `Retry-After`.",
      "example": 45,
      "minimum": 0
    }
  }
}

Status 500: The password hash could not be read, or the elevated session could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/elevate

End elevation by revoking the elevated operator session cookie.

Access: The operator (token or session) only.

Credentials: operatorSession

Responses

  • 200Elevation ended. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 400The session is not an elevated one. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is impersonating a user. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/elevate' \
    -X DELETE \
    -b 'bookclerk_operator_session=<operatorSession>' \
    -H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_operator_session', '<operatorSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/elevate' `
    -Method Delete `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/elevate",
    headers={"Cookie": "bookclerk_operator_session=<operatorSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/elevate", {
  method: "DELETE",
  headers: { Cookie: "bookclerk_operator_session=<operatorSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/elevate")
    .header("Cookie", "bookclerk_operator_session=<operatorSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Elevation ended.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 400: The session is not an elevated one.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is impersonating a user. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/bootstrap

Operator-only bootstrap of the first Owner when none exist.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: operatorToken or operatorSession

Request body

application/json: BootstrapRequest

  • display_namestring or nullOptional display name; falls back to login or email.
  • login_namestring or nullOptional local login name.
  • emailstring or nullOptional email.
  • passwordstring or nullOptional password; hashed before persist and never stored in plaintext.

Responses

  • 200The first Owner was created. Body: OwnerBootstrapped (application/json)6 fields
    • okbooleanrequiredAlways true on this success path.
    • user_idinteger (int64)requiredusers.id of the new Owner.
    • claim_ticketstringrequiredSingle-use claim ticket that signs the Owner in once (valid for seven days).
    • invite_urlstringrequiredInvite link carrying the ticket, for the browser.
    • login_namestring or nullLogin name the Owner signs in with, when one was given.
    • has_passwordbooleanrequiredWhether a password was set, so password sign-in works right away.
  • 400The email is invalid. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not the operator. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409An Owner or Administrator already exists. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/bootstrap' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/bootstrap' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/bootstrap",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/bootstrap", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/bootstrap")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The first Owner was created.

{
  "ok": true,
  "user_id": 1,
  "claim_ticket": "5f1c9a2e-7b3d-4e6f-8a90-1b2c3d4e5f60",
  "invite_url": "https://books.example.com/invite?ticket=5f1c9a2e-7b3d-4e6f-8a90-1b2c3d4e5f60",
  "login_name": "casey",
  "has_password": true
}

Schema:

{
  "type": "object",
  "description": "JSON body after the first Owner was created.",
  "required": [
    "ok",
    "user_id",
    "claim_ticket",
    "invite_url",
    "has_password"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "user_id": {
      "type": "integer",
      "format": "int64",
      "description": "`users.id` of the new Owner.",
      "example": 1
    },
    "claim_ticket": {
      "type": "string",
      "description": "Single-use claim ticket that signs the Owner in once (valid for seven days).",
      "example": "5f1c9a2e-7b3d-4e6f-8a90-1b2c3d4e5f60"
    },
    "invite_url": {
      "type": "string",
      "description": "Invite link carrying the ticket, for the browser.",
      "example": "https://books.example.com/invite?ticket=5f1c9a2e-7b3d-4e6f-8a90-1b2c3d4e5f60"
    },
    "login_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Login name the Owner signs in with, when one was given.",
      "example": "casey"
    },
    "has_password": {
      "type": "boolean",
      "description": "Whether a password was set, so password sign-in works right away.",
      "example": true
    }
  }
}

Status 400: The email is invalid. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not the operator.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 409: An Owner or Administrator already exists.

{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: display_name: invalid type: integer `1`, expected a string at line 1 column 17

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PUT /api/auth/password

Set password for self (portal) or target user (operator/admin); revokes sessions.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: operatorToken or operatorSession or portalSession

Request body

application/json: SetPasswordRequest

  • passwordstringrequiredNew password; hashed before persist. Empty is rejected.
  • current_passwordstring or nullRequired when the caller already has a password (not first-time invite setup).
  • user_idinteger (int64) or nullTarget users.id when a provisioner sets another user's password.

Responses

  • 200The password was set and other sessions revoked. Body: PasswordSet (application/json)2 fields
    • okbooleanrequiredAlways true on this success path.
    • revoked_sessionsinteger (int64)requiredPortal sessions of that user revoked by the change (the caller signs in again). At least 0.
  • 400The password is empty (the standard error body). As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in, or the caller already has a password and current_password is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller may not set that user's password: not a provisioner, or a role the caller cannot manage. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such user. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many wrong current_password attempts for this account; try again after the lockout. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The password could not be hashed, or the library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/password' \
    -X PUT \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"password": "new horse battery staple"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/password' `
    -Method Put `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"password": "new horse battery staple"}'
import requests

response = requests.put(
    "http://127.0.0.1:8787/api/auth/password",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"password": "new horse battery staple"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/password", {
  method: "PUT",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"password": "new horse battery staple"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .put("http://127.0.0.1:8787/api/auth/password")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"password": "new horse battery staple"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The password was set and other sessions revoked.

{
  "ok": true,
  "revoked_sessions": 2
}

Schema:

{
  "type": "object",
  "description": "JSON body after a password was set.",
  "required": [
    "ok",
    "revoked_sessions"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "revoked_sessions": {
      "type": "integer",
      "format": "int64",
      "description": "Portal sessions of that user revoked by the change (the caller signs in again).",
      "example": 2,
      "minimum": 0
    }
  }
}

Status 400: The password is empty (the standard error body). As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in, or the caller already has a password and current_password is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller may not set that user's password: not a provisioner, or a role the caller cannot manage.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: No such user.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `password` at line 1 column 2

Schema:

A text/plain body: a string.

Status 429: Too many wrong current_password attempts for this account; try again after the lockout.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The password could not be hashed, or the library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/password

Local password login → portal session cookie, or a TOTP challenge when enabled.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: PasswordLoginRequest

  • loginstringrequiredLogin name or email.
  • passwordstringrequiredPassword verified against the stored hash; mismatch fails closed and counts toward lockout.

Responses

  • 200Signed in (portal session cookie), or a TOTP challenge. Body: PasswordLoginOutcome (application/json)
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The login or password is wrong, or the user has no password (invalid_credentials). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403The account is disabled (account_disabled), or the server requires a second factor and the user has a passkey but no authenticator app (passkey_required). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many attempts from this client; retry after Retry-After seconds. Body: LoginThrottled (application/json)4 fields
    • errorstringrequiredAlways too_many_requests.
    • messagestringrequiredCaller-facing explanation naming the wait.
    • statusinteger (int32)requiredAlways 429 (duplicates the response status for clients). At least 0.
    • retry_after_secsinteger (int64)requiredSeconds until this client may try again; the same value as Retry-After. At least 0.
  • 500The user or password hash could not be read, or the session could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/password' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"login": "dana", "password": "correct horse battery staple"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/password' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"login": "dana", "password": "correct horse battery staple"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/password",
    json={"login": "dana", "password": "correct horse battery staple"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/password", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"login": "dana", "password": "correct horse battery staple"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/password")
    .json(&serde_json::json!({"login": "dana", "password": "correct horse battery staple"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Signed in (portal session cookie), or a TOTP challenge.

{
  "ok": true,
  "role": "member"
}

Schema:

{
  "oneOf": [
    {
      "type": "object",
      "description": "The password was enough; the response sets the portal session cookie.",
      "required": [
        "ok",
        "role"
      ],
      "properties": {
        "ok": {
          "type": "boolean",
          "description": "Always `true` on this success path.",
          "example": true
        },
        "role": {
          "type": "string",
          "description": "The user's role (`owner`, `administrator`, or `member`).",
          "example": "member"
        }
      }
    },
    {
      "type": "object",
      "description": "The user has an authenticator app, so a code is needed before a session is issued.",
      "required": [
        "ok",
        "mfa"
      ],
      "properties": {
        "ok": {
          "type": "boolean",
          "description": "Always `true`: the password step succeeded.",
          "example": true
        },
        "mfa": {
          "type": "object",
          "description": "The second step the client must complete.",
          "required": [
            "method",
            "challenge_id"
          ],
          "properties": {
            "method": {
              "type": "string",
              "description": "Always `totp`: finish with `POST /api/auth/totp/login`.",
              "example": "totp"
            },
            "challenge_id": {
              "type": "string",
              "description": "Challenge to send with the code; expires after five minutes.",
              "example": "2c7e4f0a-9b1d-4e3c-a5f6-7d8e9f0a1b2c"
            }
          }
        }
      }
    }
  ],
  "description": "JSON body of a successful `POST /api/auth/password`."
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The login or password is wrong, or the user has no password (invalid_credentials).

{
  "error": "invalid_credentials",
  "message": "Invalid login or password.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 403: The account is disabled (account_disabled), or the server requires a second factor and the user has a passkey but no authenticator app (passkey_required).

{
  "error": "account_disabled",
  "message": "This account is disabled.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `login` at line 1 column 2

Schema:

A text/plain body: a string.

Status 429: Too many attempts from this client; retry after Retry-After seconds.

{
  "error": "too_many_requests",
  "message": "Too many failed login attempts. Try again in 45 seconds.",
  "retry_after_secs": 45,
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "JSON body of a 429 after too many failed sign-in attempts from one client.",
  "required": [
    "error",
    "message",
    "status",
    "retry_after_secs"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `too_many_requests`.",
      "example": "too_many_requests"
    },
    "message": {
      "type": "string",
      "description": "Caller-facing explanation naming the wait.",
      "example": "Too many failed login attempts. Try again in 45 seconds."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Always 429 (duplicates the response status for clients).",
      "example": 429,
      "minimum": 0
    },
    "retry_after_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until this client may try again; the same value as `Retry-After`.",
      "example": 45,
      "minimum": 0
    }
  }
}

Status 500: The user or password hash could not be read, or the session could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/impersonate

Operator (or elevated) session starts impersonating a User.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Request body

application/json: ImpersonateRequest

  • user_idinteger (int64)requiredTarget users.id to impersonate.

Responses

  • 200The session now acts as the user. Body: ImpersonationStarted (application/json)2 fields
    • okbooleanrequiredAlways true on this success path.
    • impersonatingAuthMeImpersonatingrequiredThe user the session now acts as.
  • 400Operator auth is off. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is already impersonating a user, or the target user is disabled. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such user. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The user could not be read, or the session could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/impersonate' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"user_id": 7}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/impersonate' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"user_id": 7}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/impersonate",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"user_id": 7},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/impersonate", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"user_id": 7}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/impersonate")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"user_id": 7}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The session now acts as the user.

{
  "ok": true,
  "impersonating": {
    "user_id": 7,
    "display_name": "Sam"
  }
}

Schema:

{
  "type": "object",
  "description": "JSON body after an operator session started impersonating a user.",
  "required": [
    "ok",
    "impersonating"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "impersonating": {
      "type": "object",
      "description": "The user the session now acts as.",
      "required": [
        "user_id"
      ],
      "properties": {
        "user_id": {
          "type": "integer",
          "format": "int64",
          "description": "First-party `users.id` being impersonated.",
          "example": 7
        },
        "display_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Display name of the impersonated user when the row exists.",
          "example": "Sam"
        }
      }
    }
  }
}

Status 400: Operator auth is off. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is already impersonating a user, or the target user is disabled. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: No such user.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `user_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The user could not be read, or the session could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/impersonate

Clear impersonation on the current operator session.

Access: The operator (token or session) only.

Credentials: operatorSession

Responses

  • 200Impersonation ended. An elevated Owner's own portal session cookie is set again; otherwise the impersonation's portal cookie is cleared. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The session could not be updated. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/impersonate' \
    -X DELETE \
    -b 'bookclerk_operator_session=<operatorSession>' \
    -H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_operator_session', '<operatorSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/impersonate' `
    -Method Delete `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/impersonate",
    headers={"Cookie": "bookclerk_operator_session=<operatorSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/impersonate", {
  method: "DELETE",
  headers: { Cookie: "bookclerk_operator_session=<operatorSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/impersonate")
    .header("Cookie", "bookclerk_operator_session=<operatorSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Impersonation ended. An elevated Owner's own portal session cookie is set again; otherwise the impersonation's portal cookie is cleared.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The session could not be updated.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/branch-consent?<authorize params>: what the consent page shows. 400 invalid_request for a malformed request (the page then shows the problem and never redirects).

Access: The operator, or any signed-in user.

Credentials: portalSession or operatorSession

Parameters

  • client_idquerystringrequiredMust be [BRANCH_CLIENT_ID].
  • redirect_uriquerystringrequiredWhere the code goes: loopback or https.
  • response_typequerystringrequiredMust be code.
  • scopequerystringMust be [BRANCH_SCOPE].
  • statequerystringEchoed on the redirect.
  • code_challengequerystringrequiredPKCE S256 challenge.
  • code_challenge_methodquerystringMust be S256.
  • branch_namequerystringThe name the branch asks to join as.
  • shared_branch_offerquerystring1 when the joining install offers to join as a shared branch ([bookclerk_node_proto::SHARED_BRANCH_OFFER_PARAM]).

Responses

  • 200What the consent page shows. Body: BranchConsentPage (application/json)7 fields
    • library_namestringrequiredThis library's name.
    • branch_namestringrequiredThe name the branch asks to join as.
    • redirect_originstringrequiredOrigin of the branch's redirect URI, for the page to name.
    • enrollmentbooleanrequiredWhether this library lets new branches join right now.
    • userConsentingUserrequiredThe signed-in user the branch would belong to.
    • connectionConnectionChoicerequiredThe connection types the page may offer.
    • connectionsarray of ConsentConnectionrequiredThe user's store connections here, and whether each would travel to the branch if the user chooses to bring them.
  • 400The authorize parameters are invalid (invalid_request). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not a library user (user_required; an operator session counts only while impersonating), the account is inactive (user_inactive), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). Body: ErrorAnswer (application/json)
  • 503The library could not be read; try again (unavailable), or this library's identity row or origin is not available yet (library_unavailable, origin_unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ErrorAnswer or ErrorJson (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

Example response

POST /api/auth/branch-consent

POST /api/auth/branch-consent: approve or deny. Answers {redirect}, the URL to send the browser to: the branch's callback with a code (or error=access_denied). Approving needs an active signed-in user, host enrollment on, and a connection the transport policy allows.

Access: The operator, or any signed-in user.

Credentials: portalSession or operatorSession

Request body

application/json: BranchConsentBody

  • approvebooleanrequiredTrue to let the branch join; false to deny.
  • connectionstring or nullbranch (default) or shared_branch.
  • step_upStepUp or nullThe fresh second factor a shared branch needs.
  • bring_connectionsbooleanTrue to send the user's store connections that may travel to the branch when it joins. Ignored for a shared branch. Defaults to false.

Responses

  • 200{redirect} back to the branch. Body: ConsentRedirect (application/json)1 field
    • redirectstringrequiredWhere to send the browser: the branch's callback with a code, or with error=access_denied.
  • 400The body or its authorize parameters are invalid (invalid_request), or the joining server did not offer a shared branch join (shared_branch_not_offered). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not an active library user (user_required, user_inactive), this library is not accepting branches (enrollment_disabled), a shared branch join needs an Owner (owner_required) with a second factor (step_up_unavailable) that was confirmed (step_up_required) and passed (step_up_failed), the connection failed the transport policy (transport_insecure), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). A write sent with a session cookie but without a matching Origin or Referer is refused. Body: NodeRefusal (application/json)
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409This library's database cannot be shared with another server (database_not_shareable). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 413The body is larger than 8 KiB. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The request is not application/json. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 429Too many wrong step-up codes; wait a few minutes (step_up_locked). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 503The library could not be read; try again (unavailable), or this library's identity row or origin is not available yet (library_unavailable, origin_unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ErrorAnswer or ErrorJson (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/branch-consent' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{"client_id": "bookclerk-branch", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/branch-consent' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{"client_id": "bookclerk-branch", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/branch-consent",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={"client_id": "bookclerk-branch", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/branch-consent", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({"client_id": "bookclerk-branch", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/branch-consent")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({"client_id": "bookclerk-branch", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: {redirect} back to the branch.

{
  "redirect": "http://127.0.0.1:8787/api/config/join/callback?code=8f2c…&state=xyz"
}

Schema:

{
  "type": "object",
  "description": "JSON body after a branch consent was answered.",
  "required": [
    "redirect"
  ],
  "properties": {
    "redirect": {
      "type": "string",
      "description": "Where to send the browser: the branch's callback with a code, or with `error=access_denied`.",
      "example": "http://127.0.0.1:8787/api/config/join/callback?code=8f2c…&state=xyz"
    }
  }
}

Status 400: The body or its authorize parameters are invalid (invalid_request), or the joining server did not offer a shared branch join (shared_branch_not_offered).

{
  "detail": "connection must be branch or shared_branch",
  "error": "invalid_request"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is not an active library user (user_required, user_inactive), this library is not accepting branches (enrollment_disabled), a shared branch join needs an Owner (owner_required) with a second factor (step_up_unavailable) that was confirmed (step_up_required) and passed (step_up_failed), the connection failed the transport policy (transport_insecure), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "detail": "this library isn't accepting new branches",
  "error": "enrollment_disabled"
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "The connection failed the transport policy.",
      "required": [
        "error",
        "reason"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Always `transport_insecure`.",
          "example": "transport_insecure"
        },
        "reason": {
          "type": "string",
          "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
          "example": "plain_http"
        }
      }
    },
    {
      "type": "object",
      "description": "The session middleware's standard body (`error`, `message`, `status`).",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    },
    {
      "type": "object",
      "description": "The handler refused with a slug in `error`.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "The handler refused with a slug in `error` and a sentence in `detail`.",
      "required": [
        "error",
        "detail"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Stable machine slug clients branch on.",
          "example": "invalid_request"
        },
        "detail": {
          "type": "string",
          "description": "What went wrong, for the person reading the answer.",
          "example": "the redirect URI must be loopback or https"
        }
      }
    }
  ],
  "description": "A `403` from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each."
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 409: This library's database cannot be shared with another server (database_not_shareable).

{
  "detail": "This library keeps its database in a SQLite file that only this server can open. Sharing it needs a PostgreSQL or Cloudflare D1 database.",
  "error": "database_not_shareable"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 413: The body is larger than 8 KiB.

{
  "error": "request too large"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 415: The request is not application/json.

{
  "error": "expected application/json"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 429: Too many wrong step-up codes; wait a few minutes (step_up_locked).

{
  "detail": "too many wrong codes; wait a few minutes",
  "error": "step_up_locked"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 503: The library could not be read; try again (unavailable), or this library's identity row or origin is not available yet (library_unavailable, origin_unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "library_unavailable"
}

Schema:

{
  "anyOf": [
    {
      "anyOf": [
        {
          "type": "object",
          "description": "The session middleware's standard body (`error`, `message`, `status`).",
          "required": [
            "error",
            "message",
            "status"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "Machine slug (same as [`ErrorBody::code`]).",
              "example": "not_found"
            },
            "message": {
              "type": "string",
              "description": "Operator-facing explanation.",
              "example": "That page or resource was not found."
            },
            "status": {
              "type": "integer",
              "format": "int32",
              "description": "Numeric HTTP status (duplicates the response status for clients).",
              "example": 404,
              "minimum": 0
            }
          }
        },
        {
          "type": "object",
          "description": "A slug or a sentence in `error`.",
          "required": [
            "error"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "What went wrong, as the handler describes it.",
              "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
            }
          }
        },
        {
          "type": "object",
          "description": "A slug in `error` and a sentence in `detail`.",
          "required": [
            "error",
            "detail"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "Stable machine slug clients branch on.",
              "example": "invalid_request"
            },
            "detail": {
              "type": "string",
              "description": "What went wrong, for the person reading the answer.",
              "example": "the redirect URI must be loopback or https"
            }
          }
        }
      ],
      "description": "An error answer in one of several shapes: the standard body, `error` alone, or `error` with `detail`; the route's examples name each."
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/branch-consent/step-up

POST /api/auth/branch-consent/step-up: starts a passkey step-up for a shared branch consent (an Owner with a passkey). Answers the WebAuthn request options with a challenge_id to send back in the consent's step_up.

Access: The operator, or any signed-in user.

Credentials: portalSession or operatorSession

Responses

  • 200Passkey request options. Body: PasskeyRequestOptions (application/json)3 fields
    • challenge_idstringrequiredServer-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.
    • publicKeyany JSONrequiredW3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.
    • mediationstring or nullCredential mediation the daemon asks the browser for; absent unless conditional mediation was requested.
  • 400This server's public origin is not a URL WebAuthn can use, so the passkey check could not start (unavailable). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not an active library user (user_required, user_inactive), not an Owner (owner_required), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorAnswer (application/json)
  • 404The account has no passkey (no_passkey). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 500The passkeys could not be read, or the challenge could not be created or stored (unavailable). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 503The user record could not be read (unavailable); try again. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ErrorDetail or ErrorJson (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/branch-consent/step-up' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/branch-consent/step-up' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/branch-consent/step-up",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/branch-consent/step-up", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/branch-consent/step-up")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Passkey request options.

{
  "challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f",
  "publicKey": {
    "allowCredentials": [
      {
        "id": "pQECAyYgASFYIE",
        "type": "public-key"
      }
    ],
    "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
    "rpId": "books.example.com",
    "timeout": 60000,
    "userVerification": "preferred"
  },
  "mediation": "conditional"
}

Schema:

{
  "type": "object",
  "description": "WebAuthn request options for `navigator.credentials.get()`, plus the challenge id for the finish step.",
  "required": [
    "challenge_id",
    "publicKey"
  ],
  "properties": {
    "challenge_id": {
      "type": "string",
      "description": "Server-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.",
      "example": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f"
    },
    "publicKey": {
      "description": "W3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.",
      "examples": [
        {
          "allowCredentials": [
            {
              "id": "pQECAyYgASFYIE",
              "type": "public-key"
            }
          ],
          "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
          "rpId": "books.example.com",
          "timeout": 60000,
          "userVerification": "preferred"
        }
      ]
    },
    "mediation": {
      "type": [
        "string",
        "null"
      ],
      "description": "Credential mediation the daemon asks the browser for; absent unless\nconditional mediation was requested.",
      "example": "conditional"
    }
  }
}

Status 400: This server's public origin is not a URL WebAuthn can use, so the passkey check could not start (unavailable).

{
  "detail": "could not start the passkey check",
  "error": "unavailable"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is not an active library user (user_required, user_inactive), not an Owner (owner_required), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "mfa_enrollment_required",
  "message": "This server requires a passkey or authenticator app. Set one up to continue, or log out and finish later.",
  "status": 403
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "The session middleware's standard body (`error`, `message`, `status`).",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    },
    {
      "type": "object",
      "description": "A slug or a sentence in `error`.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "A slug in `error` and a sentence in `detail`.",
      "required": [
        "error",
        "detail"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Stable machine slug clients branch on.",
          "example": "invalid_request"
        },
        "detail": {
          "type": "string",
          "description": "What went wrong, for the person reading the answer.",
          "example": "the redirect URI must be loopback or https"
        }
      }
    }
  ],
  "description": "An error answer in one of several shapes: the standard body, `error` alone, or `error` with `detail`; the route's examples name each."
}

Status 404: The account has no passkey (no_passkey).

{
  "detail": "this account has no passkey",
  "error": "no_passkey"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 500: The passkeys could not be read, or the challenge could not be created or stored (unavailable).

{
  "detail": "could not start the passkey check",
  "error": "unavailable"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 503: The user record could not be read (unavailable); try again. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
      "required": [
        "error",
        "detail"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Stable machine slug clients branch on.",
          "example": "invalid_request"
        },
        "detail": {
          "type": "string",
          "description": "What went wrong, for the person reading the answer.",
          "example": "the redirect URI must be loopback or https"
        }
      }
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/clerk-consent?<authorize params>: what the consent page shows. 400 invalid_request for a malformed request (the page then shows the problem and never redirects).

Access: The operator, or any signed-in user.

Credentials: portalSession or operatorSession

Parameters

  • client_idquerystringrequiredMust be [CLERK_CLIENT_ID].
  • redirect_uriquerystringrequiredWhere the code goes: loopback or https.
  • response_typequerystringrequiredMust be code.
  • scopequerystringMust be [CLERK_SCOPE].
  • statequerystringEchoed on the redirect.
  • code_challengequerystringrequiredPKCE S256 challenge.
  • code_challenge_methodquerystringMust be S256.
  • clerk_namequerystringThe name the clerk gives itself, shown on the consent page and in the user's session list.

Responses

  • 200What the consent page shows. Body: ClerkConsentPage (application/json)4 fields
    • library_namestringrequiredThis library's name.
    • clerk_namestringrequiredThe name the clerk gives itself.
    • redirect_originstringrequiredOrigin of the clerk's redirect URI, for the page to name.
    • userConsentingUserrequiredThe signed-in user the clerk would sign in as.
  • 400The authorize parameters are invalid (invalid_request). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not a library user (user_required; an operator session counts only while impersonating), the account is inactive (user_inactive), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). Body: ErrorAnswer or ErrorJson (application/json)
  • 503The library could not be read; try again (unavailable), or this library's identity row or origin is not available yet (library_unavailable, origin_unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ErrorAnswer or ErrorJson (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

Example response

POST /api/auth/clerk-consent

POST /api/auth/clerk-consent: approve or deny. Answers {redirect}, the URL to send the browser to: the clerk's callback with a code (or error=access_denied).

Access: The operator, or any signed-in user.

Credentials: portalSession or operatorSession

Request body

application/json: ClerkConsentBody

  • approvebooleanrequiredTrue to let the clerk sign in; false to deny.

Responses

  • 200{redirect} back to the clerk. Body: ConsentRedirect (application/json)1 field
    • redirectstringrequiredWhere to send the browser: the branch's callback with a code, or with error=access_denied.
  • 400The body or its authorize parameters are invalid (invalid_request). Body: ErrorDetail (application/json)2 fields
    • errorstringrequiredStable machine slug clients branch on.
    • detailstringrequiredWhat went wrong, for the person reading the answer.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not an active library user (user_required, user_inactive), the connection failed the transport policy (transport_insecure), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). A write sent with a session cookie but without a matching Origin or Referer is refused. Body: NodeRefusal or ErrorJson (application/json)
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 413The body is larger than 8 KiB. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The request is not application/json. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The library could not be read or the code could not be stored; try again (unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ErrorDetail or ErrorJson (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/clerk-consent' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{"client_id": "bookclerk-clerk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/clerk-consent' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{"client_id": "bookclerk-clerk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/clerk-consent",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={"client_id": "bookclerk-clerk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/clerk-consent", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({"client_id": "bookclerk-clerk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/clerk-consent")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({"client_id": "bookclerk-clerk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: {redirect} back to the clerk.

{
  "redirect": "http://127.0.0.1:8787/api/config/join/callback?code=8f2c…&state=xyz"
}

Schema:

{
  "type": "object",
  "description": "JSON body after a branch consent was answered.",
  "required": [
    "redirect"
  ],
  "properties": {
    "redirect": {
      "type": "string",
      "description": "Where to send the browser: the branch's callback with a code, or with `error=access_denied`.",
      "example": "http://127.0.0.1:8787/api/config/join/callback?code=8f2c…&state=xyz"
    }
  }
}

Status 400: The body or its authorize parameters are invalid (invalid_request).

{
  "detail": "bad redirect",
  "error": "invalid_request"
}

Schema:

{
  "type": "object",
  "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
  "required": [
    "error",
    "detail"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug clients branch on.",
      "example": "invalid_request"
    },
    "detail": {
      "type": "string",
      "description": "What went wrong, for the person reading the answer.",
      "example": "the redirect URI must be loopback or https"
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is not an active library user (user_required, user_inactive), the connection failed the transport policy (transport_insecure), the session has no user account (the standard error body), or the user must enroll a second factor first (mfa_enrollment_required). A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "mfa_enrollment_required",
  "message": "This server requires a passkey or authenticator app. Set one up to continue, or log out and finish later.",
  "status": 403
}

Schema:

{
  "anyOf": [
    {
      "anyOf": [
        {
          "type": "object",
          "description": "The connection failed the transport policy.",
          "required": [
            "error",
            "reason"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "Always `transport_insecure`.",
              "example": "transport_insecure"
            },
            "reason": {
              "type": "string",
              "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
              "example": "plain_http"
            }
          }
        },
        {
          "type": "object",
          "description": "The session middleware's standard body (`error`, `message`, `status`).",
          "required": [
            "error",
            "message",
            "status"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "Machine slug (same as [`ErrorBody::code`]).",
              "example": "not_found"
            },
            "message": {
              "type": "string",
              "description": "Operator-facing explanation.",
              "example": "That page or resource was not found."
            },
            "status": {
              "type": "integer",
              "format": "int32",
              "description": "Numeric HTTP status (duplicates the response status for clients).",
              "example": 404,
              "minimum": 0
            }
          }
        },
        {
          "type": "object",
          "description": "The handler refused with a slug in `error`.",
          "required": [
            "error"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "What went wrong, as the handler describes it.",
              "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
            }
          }
        },
        {
          "type": "object",
          "description": "The handler refused with a slug in `error` and a sentence in `detail`.",
          "required": [
            "error",
            "detail"
          ],
          "properties": {
            "error": {
              "type": "string",
              "description": "Stable machine slug clients branch on.",
              "example": "invalid_request"
            },
            "detail": {
              "type": "string",
              "description": "What went wrong, for the person reading the answer.",
              "example": "the redirect URI must be loopback or https"
            }
          }
        }
      ],
      "description": "A `403` from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each."
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 413: The body is larger than 8 KiB.

{
  "error": "request too large"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 415: The request is not application/json.

{
  "error": "expected application/json"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The library could not be read or the code could not be stored; try again (unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "JSON error body with a machine slug and a longer explanation (`detail`).",
      "required": [
        "error",
        "detail"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Stable machine slug clients branch on.",
          "example": "invalid_request"
        },
        "detail": {
          "type": "string",
          "description": "What went wrong, for the person reading the answer.",
          "example": "the redirect URI must be loopback or https"
        }
      }
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/logout

Revokes hashed operator and portal sessions and clears both cookies.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Responses

  • 200Signed out; both session cookies are cleared. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503A library card's session could not be ended (sign_out_failed); the card is still signed in, so try again. Clearing cookies does not end a card. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/logout' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/logout' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/logout",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/logout", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/logout")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Signed out; both session cookies are cleared.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 503: A library card's session could not be ended (sign_out_failed); the card is still signed in, so try again. Clearing cookies does not end a card. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/sessions

List sessions for the current principal only (not every operator session).

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Responses

  • 200The caller's sessions. Body: SessionsResponse (application/json)1 field
    • sessionsarray of SessionViewrequiredThe caller's sessions, newest first; empty for a Bearer-only caller, who has no session rows.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404The impersonated user has no sign-in identity. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The sessions could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/sessions' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/sessions' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/sessions",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/sessions", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/sessions")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's sessions.

{
  "sessions": [
    {
      "id": 12,
      "created_at": "2026-10-28T19:02:11Z",
      "last_used_at": "2026-10-29T08:15:00Z",
      "expires_at": "2026-11-04T19:02:11Z",
      "elevated": false,
      "impersonating_user_id": 7,
      "is_current": false,
      "client_label": "Windows",
      "device_type": "desktop",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Firefox/134.0",
      "kind": "operator"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/sessions`.",
  "required": [
    "sessions"
  ],
  "properties": {
    "sessions": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "allOf": [
              {
                "type": "object",
                "description": "An operator session (`kind` is `operator`).",
                "required": [
                  "id",
                  "created_at",
                  "expires_at",
                  "elevated",
                  "is_current"
                ],
                "properties": {
                  "id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Session id, for `DELETE /api/auth/sessions/{id}`.",
                    "example": 12
                  },
                  "created_at": {
                    "type": "string",
                    "description": "RFC 3339 time the session was created.",
                    "example": "2026-10-28T19:02:11Z"
                  },
                  "last_used_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time of the last authenticated use, when any.",
                    "example": "2026-10-29T08:15:00Z"
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "RFC 3339 expiry.",
                    "example": "2026-11-04T19:02:11Z"
                  },
                  "elevated": {
                    "type": "boolean",
                    "description": "Whether an Owner elevated into this session (rather than the operator token).",
                    "example": false
                  },
                  "impersonating_user_id": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "User the session is impersonating, when it is. Never set on the\nsession making the request: while that session impersonates, the\nlist shows the target's portal sessions instead.",
                    "example": 7
                  },
                  "is_current": {
                    "type": "boolean",
                    "description": "Whether this is the session making the request.",
                    "example": false
                  },
                  "client_label": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Best-effort OS or client label from the User-Agent.",
                    "example": "Windows"
                  },
                  "device_type": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Best-effort device class (`desktop`, `mobile`, `tablet`, `api`).",
                    "example": "desktop"
                  },
                  "user_agent": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Raw User-Agent captured when the session was created.",
                    "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Firefox/134.0"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "operator"
                    ]
                  }
                }
              }
            ],
            "description": "An operator session (`kind` is `operator`)."
          },
          {
            "allOf": [
              {
                "type": "object",
                "description": "A portal session (`kind` is `portal`).",
                "required": [
                  "id",
                  "created_at",
                  "expires_at",
                  "is_current",
                  "channel"
                ],
                "properties": {
                  "id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Session id, for `DELETE /api/auth/sessions/{id}`.",
                    "example": 31
                  },
                  "created_at": {
                    "type": "string",
                    "description": "RFC 3339 time the session was created.",
                    "example": "2026-10-28T19:02:11Z"
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "RFC 3339 expiry.",
                    "example": "2026-11-27T19:02:11Z"
                  },
                  "last_used_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time of the last authenticated use, when any.",
                    "example": "2026-10-29T08:15:00Z"
                  },
                  "is_current": {
                    "type": "boolean",
                    "description": "Whether this is the session making the request.",
                    "example": true
                  },
                  "client_label": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Best-effort OS or client label from the User-Agent.",
                    "example": "Android"
                  },
                  "device_type": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Best-effort device class (`desktop`, `mobile`, `tablet`, `api`).",
                    "example": "mobile"
                  },
                  "user_agent": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Raw User-Agent captured when the session was created.",
                    "example": "Mozilla/5.0 (Linux; Android 15) Chrome/131.0 Mobile"
                  },
                  "channel": {
                    "type": "string",
                    "description": "How the session is used: `browser` for a browser session, `clerk`\nfor a library card, whose `client_label` is the name the clerk gave\nitself, `player` for a player app's card (`/player`), whose\n`client_label` is the player password's label or the app's name.",
                    "enum": [
                      "browser",
                      "clerk",
                      "player"
                    ]
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "portal"
                    ]
                  }
                }
              }
            ],
            "description": "A portal session (`kind` is `portal`)."
          }
        ],
        "description": "One session in the caller's list, told apart by `kind`: an operator\nsession or a portal (user) session."
      },
      "description": "The caller's sessions, newest first; empty for a Bearer-only caller, who has no session rows."
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: The impersonated user has no sign-in identity.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The sessions could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/sessions/{id}

Revoke a session by id. Operators may revoke any operator session; portal users may only revoke their own.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Parameters

  • idpathinteger (int64)requiredSession id.

Responses

  • 200The session was revoked. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404No such session, or it belongs to someone else. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The session could not be deleted. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/sessions/<id>' \
    -X DELETE \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/sessions/<id>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/sessions/<id>",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/sessions/<id>", {
  method: "DELETE",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/sessions/<id>")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The session was revoked.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: No such session, or it belongs to someone else.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The session could not be deleted.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PATCH /api/auth/profile

Updates the caller's display name and/or email.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Request body

application/json: PatchProfileRequest

  • display_namestring or nullReplacement display name; empty or whitespace clears the field.
  • emailstring or nullReplacement email; empty or whitespace clears the field.
  • avatar_sourcestring or nullPicture choice (auto, monogram, gravatar, upload, or sso:{id}).

Responses

  • 200The profile after the change. Body: ProfileChanged (application/json)2 fields
    • okbooleanrequiredAlways true on this success path.
    • userAuthMeUserrequiredThe profile after the change, as GET /api/auth/me reports it.
  • 400A value is invalid (display_name_too_long, invalid_email, invalid_avatar_source), or the body sets none of the three fields (the standard error body). As text/plain, when the body is not syntactically valid JSON. Body: ErrorJson (application/json); string (text/plain)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404The caller's user no longer exists. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409The email is used by another account (email_in_use). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/profile' \
    -X PATCH \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/profile' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.patch(
    "http://127.0.0.1:8787/api/auth/profile",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/profile", {
  method: "PATCH",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .patch("http://127.0.0.1:8787/api/auth/profile")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The profile after the change.

{
  "ok": true,
  "user": {
    "id": 7,
    "role": "administrator",
    "display_name": "Sam",
    "email": "sam@example.com",
    "has_password": true,
    "has_avatar": false,
    "avatar_source": "auto",
    "gravatar_hash": "0bc83cb571cd1c50ba6f3e8a78ef1346b6b31bd4d35b8d3dc1f0c8a3b4a9f7e2",
    "sso_pictures": [
      {
        "identity_id": 3,
        "provider": "oidc:google",
        "picture_url": "https://lh3.googleusercontent.com/a/example=s96-c",
        "picture_path": "/api/images/aHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EvZXhhbXBsZT1zOTYtYw.N14rqh66Bok9-eCqJKBNoQ",
        "last_used_at": "2026-10-29T08:15:00Z"
      }
    ]
  }
}

Schema:

{
  "type": "object",
  "description": "JSON body after `PATCH /api/auth/profile`.",
  "required": [
    "ok",
    "user"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "user": {
      "type": "object",
      "description": "The profile after the change, as `GET /api/auth/me` reports it.",
      "required": [
        "id",
        "role",
        "has_password",
        "has_avatar",
        "avatar_source"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "First-party `users.id`.",
          "example": 7
        },
        "role": {
          "type": "string",
          "description": "Role string (`owner`, `administrator`, `member`).",
          "example": "administrator"
        },
        "display_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional human-readable name from the user row.",
          "example": "Sam"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional email; omitted from JSON when unset.",
          "example": "sam@example.com"
        },
        "has_password": {
          "type": "boolean",
          "description": "True when a local password hash is stored (invite users may be false).",
          "example": true
        },
        "has_avatar": {
          "type": "boolean",
          "description": "True when a JPEG avatar is stored under `files_dir/avatars/{id}.*`.",
          "example": false
        },
        "avatar_source": {
          "type": "string",
          "description": "Selected picture source (`auto`, `monogram`, `gravatar`, `upload`, `sso:{id}`).",
          "example": "auto"
        },
        "gravatar_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "SHA-256 hex of the contact email for Gravatar, when an email is set.",
          "example": "0bc83cb571cd1c50ba6f3e8a78ef1346b6b31bd4d35b8d3dc1f0c8a3b4a9f7e2"
        },
        "sso_pictures": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "HTTPS picture from a linked identity provider.",
            "required": [
              "identity_id",
              "provider",
              "picture_url"
            ],
            "properties": {
              "identity_id": {
                "type": "integer",
                "format": "int64",
                "description": "`portal_identities.id`.",
                "example": 3
              },
              "provider": {
                "type": "string",
                "description": "Identity-broker id (`oidc:google`, …).",
                "example": "oidc:google"
              },
              "picture_url": {
                "type": "string",
                "description": "HTTPS URL to display.",
                "example": "https://lh3.googleusercontent.com/a/example=s96-c"
              },
              "picture_path": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Same-origin 128 px copy of `picture_url` for the web app to show,\nwhen this node can sign it.",
                "example": "/api/images/aHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EvZXhhbXBsZT1zOTYtYw.N14rqh66Bok9-eCqJKBNoQ"
              },
              "last_used_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "RFC 3339 last portal-session activity for this identity, when any.",
                "example": "2026-10-29T08:15:00Z"
              }
            }
          },
          "description": "IdP-supplied pictures the user can pick."
        }
      }
    }
  }
}

Status 400: A value is invalid (display_name_too_long, invalid_email, invalid_avatar_source), or the body sets none of the three fields (the standard error body). As text/plain, when the body is not syntactically valid JSON.

{
  "error": "display_name_too_long",
  "message": "Display name must be 80 characters or fewer.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: The caller's user no longer exists.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 409: The email is used by another account (email_in_use).

{
  "error": "email_in_use",
  "message": "That email is already used by another account.",
  "status": 409
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: display_name: invalid type: integer `1`, expected a string at line 1 column 17

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/profile/catalog-listing

Reads whether the caller's books are listed to the libraries this install is a branch of.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Responses

  • 200The caller's listing choice. Body: CatalogListingView (application/json)3 fields
    • listedbooleanrequiredThe caller's choice; see [CatalogListing::listed].
    • librariesinteger (int32)requiredLibraries this install is currently a branch of (active links). With none, the choice has no effect yet, and the app hides it. At least 0.
    • always_listedbooleanrequiredtrue for an active Owner: an Owner's books are always listed, so listed has no effect and the app shows that instead of the toggle.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The library could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/profile/catalog-listing' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/profile/catalog-listing' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/profile/catalog-listing",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/profile/catalog-listing", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/profile/catalog-listing")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's listing choice.

{
  "listed": true,
  "libraries": 1,
  "always_listed": false
}

Schema:

{
  "type": "object",
  "description": "The caller's listing choice and how many libraries it applies to.",
  "required": [
    "listed",
    "libraries",
    "always_listed"
  ],
  "properties": {
    "listed": {
      "type": "boolean",
      "description": "The caller's choice; see [`CatalogListing::listed`].",
      "example": true
    },
    "libraries": {
      "type": "integer",
      "format": "int32",
      "description": "Libraries this install is currently a branch of (active links).\nWith none, the choice has no effect yet, and the app hides it.",
      "example": 1,
      "minimum": 0
    },
    "always_listed": {
      "type": "boolean",
      "description": "`true` for an active Owner: an Owner's books are always listed, so\n`listed` has no effect and the app shows that instead of the toggle.",
      "example": false
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The library could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PUT /api/auth/profile/catalog-listing

Sets whether the caller's books are listed to the libraries this install is a branch of.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Request body

application/json: CatalogListing

  • listedbooleanrequiredtrue (the default): the libraries this install joined can see, when they ask, that it can supply the caller's books. false keeps them out of those answers; the owner's books are always listed.

Responses

  • 200The caller's listing choice after the change. Body: CatalogListingView (application/json)3 fields
    • listedbooleanrequiredThe caller's choice; see [CatalogListing::listed].
    • librariesinteger (int32)requiredLibraries this install is currently a branch of (active links). With none, the choice has no effect yet, and the app hides it. At least 0.
    • always_listedbooleanrequiredtrue for an active Owner: an Owner's books are always listed, so listed has no effect and the app shows that instead of the toggle.
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/profile/catalog-listing' \
    -X PUT \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"listed": true}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/profile/catalog-listing' `
    -Method Put `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"listed": true}'
import requests

response = requests.put(
    "http://127.0.0.1:8787/api/auth/profile/catalog-listing",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"listed": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/profile/catalog-listing", {
  method: "PUT",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"listed": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .put("http://127.0.0.1:8787/api/auth/profile/catalog-listing")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"listed": true}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's listing choice after the change.

{
  "listed": true,
  "libraries": 1,
  "always_listed": false
}

Schema:

{
  "type": "object",
  "description": "The caller's listing choice and how many libraries it applies to.",
  "required": [
    "listed",
    "libraries",
    "always_listed"
  ],
  "properties": {
    "listed": {
      "type": "boolean",
      "description": "The caller's choice; see [`CatalogListing::listed`].",
      "example": true
    },
    "libraries": {
      "type": "integer",
      "format": "int32",
      "description": "Libraries this install is currently a branch of (active links).\nWith none, the choice has no effect yet, and the app hides it.",
      "example": 1,
      "minimum": 0
    },
    "always_listed": {
      "type": "boolean",
      "description": "`true` for an active Owner: an Owner's books are always listed, so\n`listed` has no effect and the app shows that instead of the toggle.",
      "example": false
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `listed` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PUT /api/auth/profile/avatar

Accepts a JPEG/PNG/WebP upload and stores it under files_dir/avatars.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Request body

image/*: BinaryBody

Responses

  • 200The avatar was stored. Body: AvatarChanged (application/json)3 fields
    • okbooleanrequiredAlways true on this success path.
    • has_avatarbooleanrequiredWhether an uploaded picture is stored now.
    • avatar_sourcestring or nullPresent only after an upload, always upload; absent after a removal (the stored source is then unchanged unless it was upload).
  • 400The body is empty or not a JPEG, PNG or WebP image. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 413The image is larger than 1.5 MB. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The files directory is unknown, or the image could not be written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/profile/avatar' \
    -X PUT \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: image/*' \
    --data-binary @file
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/profile/avatar' `
    -Method Put `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'image/*' `
    -InFile 'file'
import requests

response = requests.put(
    "http://127.0.0.1:8787/api/auth/profile/avatar",
    headers={"Authorization": "Bearer <operatorToken>", "Content-Type": "image/*"},
    data=open("file", "rb"),
)
print(response.status_code, response.text)
import { readFile } from "node:fs/promises";

const response = await fetch("http://127.0.0.1:8787/api/auth/profile/avatar", {
  method: "PUT",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "image/*" },
  body: await readFile("file"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .put("http://127.0.0.1:8787/api/auth/profile/avatar")
    .header("Authorization", "Bearer <operatorToken>")
    .header("Content-Type", "image/*")
    .body(std::fs::read("file")?)
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The avatar was stored.

{
  "ok": true,
  "has_avatar": true,
  "avatar_source": "upload"
}

Schema:

{
  "type": "object",
  "description": "JSON body after the caller's avatar was stored or removed.",
  "required": [
    "ok",
    "has_avatar"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "has_avatar": {
      "type": "boolean",
      "description": "Whether an uploaded picture is stored now.",
      "example": true
    },
    "avatar_source": {
      "type": [
        "string",
        "null"
      ],
      "description": "Present only after an upload, always `upload`; absent after a removal\n(the stored source is then unchanged unless it was `upload`).",
      "example": "upload"
    }
  }
}

Status 400: The body is empty or not a JPEG, PNG or WebP image.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 413: The image is larger than 1.5 MB.

{
  "error": "payload_too_large",
  "message": "Payload Too Large",
  "status": 413
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The files directory is unknown, or the image could not be written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/profile/avatar

Removes the caller's stored avatar, if any.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Responses

  • 200The avatar was removed. Body: AvatarChanged (application/json)3 fields
    • okbooleanrequiredAlways true on this success path.
    • has_avatarbooleanrequiredWhether an uploaded picture is stored now.
    • avatar_sourcestring or nullPresent only after an upload, always upload; absent after a removal (the stored source is then unchanged unless it was upload).
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The files directory is unknown. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/profile/avatar' \
    -X DELETE \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/profile/avatar' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/profile/avatar",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/profile/avatar", {
  method: "DELETE",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/profile/avatar")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The avatar was removed.

{
  "has_avatar": false,
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "JSON body after the caller's avatar was stored or removed.",
  "required": [
    "ok",
    "has_avatar"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "has_avatar": {
      "type": "boolean",
      "description": "Whether an uploaded picture is stored now.",
      "example": true
    },
    "avatar_source": {
      "type": [
        "string",
        "null"
      ],
      "description": "Present only after an upload, always `upload`; absent after a removal\n(the stored source is then unchanged unless it was `upload`).",
      "example": "upload"
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The session is impersonating a user, is a plain operator session, or has no first-party user. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The files directory is unknown.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/oidc/providers

Lists enabled IdPs for the login picker (id and display name only).

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 200Enabled identity providers (id and name). Body: OidcProvidersResponse (application/json)2 fields
    • enabledbooleanrequiredWhether the OIDC broker is switched on at all.
    • providersarray of SigninOidcProviderrequiredProviders enabled in configuration, in configuration order (empty while the broker is off).
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/providers'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/providers'
import requests

response = requests.get("http://127.0.0.1:8787/api/auth/oidc/providers")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/providers");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/auth/oidc/providers").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Enabled identity providers (id and name).

{
  "enabled": true,
  "providers": [
    {
      "id": "google",
      "name": "Google",
      "preset": "google"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/oidc/providers`.",
  "required": [
    "enabled",
    "providers"
  ],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether the OIDC broker is switched on at all.",
      "example": true
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One OIDC identity provider offered on the sign-in page.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Provider id from `[auth.oidc.providers]`, used in `/api/auth/oidc/{id}/start`.",
            "example": "google"
          },
          "name": {
            "type": "string",
            "description": "Button label.",
            "example": "Google"
          },
          "preset": {
            "type": [
              "string",
              "null"
            ],
            "description": "Known social preset the client may style (`google`, `github`, …), when the provider matches one.",
            "example": "google"
          }
        }
      },
      "description": "Providers enabled in configuration, in configuration order (empty while the broker is off)."
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/oidc/identities

Lists OIDC portal identities for the cookie-authenticated caller.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Responses

  • 200The caller's linked identities. Body: LinkedIdentitiesResponse (application/json)1 field
    • identitiesarray of LinkedIdentityrequiredEvery sign-in identity linked to the caller's user, the local one included.
  • 401The caller is not signed in, or has no first-party user. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The identities could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/identities' \
    -b 'bookclerk_portal_session=<portalSession>'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/identities' `
    -WebSession $session
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/oidc/identities",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/identities", {
  headers: { Cookie: "bookclerk_portal_session=<portalSession>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/oidc/identities")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's linked identities.

{
  "identities": [
    {
      "provider": "oidc:google",
      "external_user_id": "118234509876543210987",
      "label": "sam@example.com"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/oidc/identities`.",
  "required": [
    "identities"
  ],
  "properties": {
    "identities": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One sign-in identity linked to a user.",
        "required": [
          "provider",
          "external_user_id"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "description": "Identity-broker id (`local`, `oidc:google`, …).",
            "example": "oidc:google"
          },
          "external_user_id": {
            "type": "string",
            "description": "Provider-stable subject.",
            "example": "118234509876543210987"
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator-facing label, when the provider supplied one.",
            "example": "sam@example.com"
          }
        }
      },
      "description": "Every sign-in identity linked to the caller's user, the local one included."
    }
  }
}

Status 401: The caller is not signed in, or has no first-party user.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The identities could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/oidc/login

Starts an OIDC login authorize redirect, honoring login throttle.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • providerquerystringIdP id to start; omitted when the caller has only one enabled provider.

Responses

  • 307Redirects to the identity provider, with the transaction cookie set. No body.
  • 400No provider was named. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404OIDC sign-in is disabled, or no enabled provider has this id. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 429Too many attempts; retry after Retry-After seconds. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The transaction could not be stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 502The provider's discovery document could not be fetched. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/login'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/login'
import requests

response = requests.get("http://127.0.0.1:8787/api/auth/oidc/login")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/login");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/auth/oidc/login").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 307: Redirects to the identity provider, with the transaction cookie set. No body.

Status 400: No provider was named. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: OIDC sign-in is disabled, or no enabled provider has this id. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 429: Too many attempts; retry after Retry-After seconds. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The transaction could not be stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 502: The provider's discovery document could not be fetched. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_gateway",
  "message": "An upstream service failed.",
  "status": 502
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/oidc/elevate

Starts an Owner re-auth elevate flow against a linked IdP (prompt=login).

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Parameters

  • providerquerystringIdP id to start; omitted when the caller has only one enabled provider.

Responses

  • 307Redirects to the identity provider for re-authentication, with the transaction cookie set. No body.
  • 400No provider was named and the Owner has no linked OIDC identity. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403The caller is not an Owner. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404OIDC sign-in is disabled, or no enabled provider has this id. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 429Too many attempts; retry after Retry-After seconds. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The linked identities or the transaction could not be read or stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 502The provider's discovery document could not be fetched. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: string (text/html); ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/elevate' \
    -b 'bookclerk_portal_session=<portalSession>'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/elevate' `
    -WebSession $session
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/oidc/elevate",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/elevate", {
  headers: { Cookie: "bookclerk_portal_session=<portalSession>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/oidc/elevate")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 307: Redirects to the identity provider for re-authentication, with the transaction cookie set. No body.

Status 400: No provider was named and the Owner has no linked OIDC identity. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 401: The caller is not signed in. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 403: The caller is not an Owner. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: OIDC sign-in is disabled, or no enabled provider has this id. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 429: Too many attempts; retry after Retry-After seconds. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The linked identities or the transaction could not be read or stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 502: The provider's discovery document could not be fetched. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_gateway",
  "message": "An upstream service failed.",
  "status": 502
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/oidc/callback

GET callback (most IdPs); finishes the code exchange.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • codequerystringAuthorization code to exchange; required unless error is set.
  • statequerystringCSRF state that must match the bookclerk_oidc_tx cookie.
  • errorquerystringIdP-reported deny/error; redirects the browser to /?sso_error=denied.
  • userquerystringApple first-login name/email JSON (form_post only).

Responses

  • 303Redirects into the app: to / signed in, to /settings after an elevation, or with sso_error naming why sign-in did not finish (denied, csrf, expired, nonce, sub, disabled, no_role, conflict, mismatch). No body.
  • 400The code or the state is missing, or an elevation has no user. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403The elevated user is not an Owner. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404OIDC sign-in is disabled, the provider is gone, or the elevated user no longer exists. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The transaction, the identities or the user could not be read or stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 502The provider's discovery, token, keys or userinfo endpoint failed, or its tokens were unusable. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/callback'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/callback'
import requests

response = requests.get("http://127.0.0.1:8787/api/auth/oidc/callback")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/callback");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/auth/oidc/callback").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 303: Redirects into the app: to / signed in, to /settings after an elevation, or with sso_error naming why sign-in did not finish (denied, csrf, expired, nonce, sub, disabled, no_role, conflict, mismatch). No body.

Status 400: The code or the state is missing, or an elevation has no user. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 403: The elevated user is not an Owner. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: OIDC sign-in is disabled, the provider is gone, or the elevated user no longer exists. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The transaction, the identities or the user could not be read or stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 502: The provider's discovery, token, keys or userinfo endpoint failed, or its tokens were unusable. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_gateway",
  "message": "An upstream service failed.",
  "status": 502
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/oidc/callback

POST callback (Apple form_post); finishes the code exchange.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/x-www-form-urlencoded: CallbackParams

  • codestring or nullAuthorization code to exchange; required unless error is set.
  • statestring or nullCSRF state that must match the bookclerk_oidc_tx cookie.
  • errorstring or nullIdP-reported deny/error; redirects the browser to /?sso_error=denied.
  • userstring or nullApple first-login name/email JSON (form_post only).

Responses

  • 303Redirects into the app: to / signed in, to /settings after an elevation, or with sso_error naming why sign-in did not finish (denied, csrf, expired, nonce, sub, disabled, no_role, conflict, mismatch). No body.
  • 400The code or the state is missing, or an elevation has no user. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403The elevated user is not an Owner. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404OIDC sign-in is disabled, the provider is gone, or the elevated user no longer exists. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The transaction, the identities or the user could not be read or stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 502The provider's discovery, token, keys or userinfo endpoint failed, or its tokens were unusable. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/callback' \
    -X POST
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/callback' `
    -Method Post
import requests

response = requests.post("http://127.0.0.1:8787/api/auth/oidc/callback")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/callback", {
  method: "POST",
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/oidc/callback")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 303: Redirects into the app: to / signed in, to /settings after an elevation, or with sso_error naming why sign-in did not finish (denied, csrf, expired, nonce, sub, disabled, no_role, conflict, mismatch). No body.

Status 400: The code or the state is missing, or an elevation has no user. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 403: The elevated user is not an Owner. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: OIDC sign-in is disabled, the provider is gone, or the elevated user no longer exists. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The transaction, the identities or the user could not be read or stored. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 502: The provider's discovery, token, keys or userinfo endpoint failed, or its tokens were unusable. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body.

{
  "error": "bad_gateway",
  "message": "An upstream service failed.",
  "status": 502
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/oidc/config

Operator GET: broker settings plus secret-presence flags (never plaintext).

Access: The operator, or a signed-in Owner.

Credentials: operatorToken or operatorSession or portalSession

Responses

  • 200Broker settings, with secrets as presence flags. Body: OidcConfigResponse (application/json)12 fields
    • enabledbooleanrequiredWhether the broker accepts new authorize starts.
    • allowed_email_domainsarray of stringrequiredBroker-wide email domain allowlist applied before per-provider rules.
    • public_originstring or nullConfigured integrations.public_origin (issuer / callback / invite base).
    • issuer_urlstringrequiredEffective issuer origin (public_origin, else this request, else localhost).
    • detected_originstringrequiredOrigin detected from this request (loopback IPs rewritten to localhost).
    • discovery_urlstringrequiredAbsolute OpenID discovery URL (/.well-known/openid-configuration).
    • authorization_endpointstringrequiredAbsolute authorization endpoint (/oidc/authorize) for Bookclerk-as-IdP.
    • token_endpointstringrequiredAbsolute token endpoint (/oidc/token) for Bookclerk-as-IdP.
    • userinfo_endpointstringrequiredAbsolute userinfo endpoint (/oidc/userinfo) for Bookclerk-as-IdP.
    • revocation_endpointstringrequiredAbsolute revocation endpoint (/oidc/revoke) for Bookclerk-as-IdP.
    • callback_urlstringrequiredAbsolute /api/auth/oidc/callback derived from the effective issuer origin.
    • providersarray of OidcProviderViewrequiredConfigured IdPs with presence flags instead of secret material.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is neither the operator nor an Owner (forbidden), or must enroll a second factor first (mfa_enrollment_required). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/config' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/config' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/oidc/config",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/config", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/oidc/config")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Broker settings, with secrets as presence flags.

{
  "enabled": true,
  "allowed_email_domains": [
    "example.com"
  ],
  "public_origin": "https://books.example.com",
  "issuer_url": "https://books.example.com",
  "detected_origin": "http://localhost:8787",
  "discovery_url": "https://books.example.com/.well-known/openid-configuration",
  "authorization_endpoint": "https://books.example.com/oidc/authorize",
  "token_endpoint": "https://books.example.com/oidc/token",
  "userinfo_endpoint": "https://books.example.com/oidc/userinfo",
  "revocation_endpoint": "https://books.example.com/oidc/revoke",
  "callback_url": "https://books.example.com/api/auth/oidc/callback",
  "providers": [
    {
      "id": "google",
      "name": "Google",
      "preset": "google",
      "issuer": "https://accounts.google.com",
      "client_id": "123456789012-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.apps.googleusercontent.com",
      "scopes": [
        "openid",
        "profile",
        "email"
      ],
      "provision": "allowlist",
      "default_role": "member",
      "role_claim": "groups",
      "role_map": {},
      "link_by_email": true,
      "allowed_email_domains": [
        "example.com"
      ],
      "allowed_emails": [
        "dana@example.com"
      ],
      "allowed_subjects": [
        "248289761001"
      ],
      "apple_team_id": "A1B2C3D4E5",
      "apple_key_id": "K9L8M7N6P5",
      "has_client_secret": true,
      "has_apple_private_key": false,
      "secret_source": "store"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "Operator-facing OIDC broker snapshot; secret material is never included.",
  "required": [
    "enabled",
    "allowed_email_domains",
    "issuer_url",
    "detected_origin",
    "discovery_url",
    "authorization_endpoint",
    "token_endpoint",
    "userinfo_endpoint",
    "revocation_endpoint",
    "callback_url",
    "providers"
  ],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether the broker accepts new authorize starts.",
      "example": true
    },
    "allowed_email_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Broker-wide email domain allowlist applied before per-provider rules.",
      "example": [
        "example.com"
      ]
    },
    "public_origin": {
      "type": [
        "string",
        "null"
      ],
      "description": "Configured `integrations.public_origin` (issuer / callback / invite base).",
      "example": "https://books.example.com"
    },
    "issuer_url": {
      "type": "string",
      "description": "Effective issuer origin (`public_origin`, else this request, else localhost).",
      "example": "https://books.example.com"
    },
    "detected_origin": {
      "type": "string",
      "description": "Origin detected from this request (loopback IPs rewritten to `localhost`).",
      "example": "http://localhost:8787"
    },
    "discovery_url": {
      "type": "string",
      "description": "Absolute OpenID discovery URL (`/.well-known/openid-configuration`).",
      "example": "https://books.example.com/.well-known/openid-configuration"
    },
    "authorization_endpoint": {
      "type": "string",
      "description": "Absolute authorization endpoint (`/oidc/authorize`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/authorize"
    },
    "token_endpoint": {
      "type": "string",
      "description": "Absolute token endpoint (`/oidc/token`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/token"
    },
    "userinfo_endpoint": {
      "type": "string",
      "description": "Absolute userinfo endpoint (`/oidc/userinfo`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/userinfo"
    },
    "revocation_endpoint": {
      "type": "string",
      "description": "Absolute revocation endpoint (`/oidc/revoke`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/revoke"
    },
    "callback_url": {
      "type": "string",
      "description": "Absolute `/api/auth/oidc/callback` derived from the effective issuer origin.",
      "example": "https://books.example.com/api/auth/oidc/callback"
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One IdP as shown to an operator (no client secret or Apple PEM).",
        "required": [
          "id",
          "name",
          "client_id",
          "scopes",
          "provision",
          "default_role",
          "role_claim",
          "role_map",
          "link_by_email",
          "allowed_email_domains",
          "allowed_emails",
          "allowed_subjects",
          "has_client_secret",
          "has_apple_private_key",
          "secret_source"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable provider id used in authorize URLs and sealed-row names.",
            "example": "google"
          },
          "name": {
            "type": "string",
            "description": "Operator-facing display name.",
            "example": "Google"
          },
          "preset": {
            "type": [
              "string",
              "null"
            ],
            "description": "Built-in social preset (`google`, `github`, `apple`, `discord`) when not a generic issuer.",
            "example": "google"
          },
          "issuer": {
            "type": [
              "string",
              "null"
            ],
            "description": "OpenID issuer URL for discovery when no social preset applies.",
            "example": "https://accounts.google.com"
          },
          "client_id": {
            "type": "string",
            "description": "OAuth client id registered at the IdP.",
            "example": "123456789012-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.apps.googleusercontent.com"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OAuth scopes requested at authorize.",
            "example": [
              "openid",
              "profile",
              "email"
            ]
          },
          "provision": {
            "type": "string",
            "description": "How a first login becomes a portal user (JIT, mapped role, allowlist, invite-only).",
            "example": "allowlist"
          },
          "default_role": {
            "type": "string",
            "description": "Portal role used when no mapped claim matches (`member` by default).",
            "example": "member"
          },
          "role_claim": {
            "type": "string",
            "description": "Claim name read from id_token/userinfo for role mapping (`groups` by default).",
            "example": "groups"
          },
          "role_map": {
            "type": "object",
            "description": "IdP group/role claim values mapped onto Bookclerk portal roles.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            },
            "example": {}
          },
          "link_by_email": {
            "type": "boolean",
            "description": "When true, a verified email may attach this IdP to an existing user.",
            "example": true
          },
          "allowed_email_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Per-provider email domain allowlist (in addition to the broker-wide list).",
            "example": [
              "example.com"
            ]
          },
          "allowed_emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exact emails permitted under allowlist provision.",
            "example": [
              "dana@example.com"
            ]
          },
          "allowed_subjects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exact IdP subject ids permitted under allowlist provision.",
            "example": [
              "248289761001"
            ]
          },
          "apple_team_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apple Developer team id used to mint the client-secret JWT.",
            "example": "A1B2C3D4E5"
          },
          "apple_key_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apple Sign In key id paired with the sealed private key.",
            "example": "K9L8M7N6P5"
          },
          "has_client_secret": {
            "type": "boolean",
            "description": "Whether a client secret exists in env, TOML, or the sealed store (value never returned).",
            "example": true
          },
          "has_apple_private_key": {
            "type": "boolean",
            "description": "Whether an Apple PEM exists in env, TOML, or the sealed store (PEM never returned).",
            "example": false
          },
          "secret_source": {
            "type": "string",
            "description": "Where the client secret was found: `env`, `config`, `store`, or `none`.",
            "example": "store"
          }
        }
      },
      "description": "Configured IdPs with presence flags instead of secret material."
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is neither the operator nor an Owner (forbidden), or must enroll a second factor first (mfa_enrollment_required).

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PUT /api/auth/oidc/config

Operator-only PUT: writes next-generation sealed secrets, then publishes config.toml.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Request body

application/json: OidcConfigPut

  • enabledbooleanrequiredWhether the broker should accept authorize starts after this write.
  • allowed_email_domainsarray of stringReplacement broker-wide email domain allowlist.
  • providersarray of OidcProviderPutFull replacement list of IdPs (omitted secrets keep the previous generation).
  • public_originstring or nullintegrations.public_origin. Omit to leave unchanged; empty string clears.

Responses

  • 200The settings after the change. Body: OidcConfigResponse (application/json)12 fields
    • enabledbooleanrequiredWhether the broker accepts new authorize starts.
    • allowed_email_domainsarray of stringrequiredBroker-wide email domain allowlist applied before per-provider rules.
    • public_originstring or nullConfigured integrations.public_origin (issuer / callback / invite base).
    • issuer_urlstringrequiredEffective issuer origin (public_origin, else this request, else localhost).
    • detected_originstringrequiredOrigin detected from this request (loopback IPs rewritten to localhost).
    • discovery_urlstringrequiredAbsolute OpenID discovery URL (/.well-known/openid-configuration).
    • authorization_endpointstringrequiredAbsolute authorization endpoint (/oidc/authorize) for Bookclerk-as-IdP.
    • token_endpointstringrequiredAbsolute token endpoint (/oidc/token) for Bookclerk-as-IdP.
    • userinfo_endpointstringrequiredAbsolute userinfo endpoint (/oidc/userinfo) for Bookclerk-as-IdP.
    • revocation_endpointstringrequiredAbsolute revocation endpoint (/oidc/revoke) for Bookclerk-as-IdP.
    • callback_urlstringrequiredAbsolute /api/auth/oidc/callback derived from the effective issuer origin.
    • providersarray of OidcProviderViewrequiredConfigured IdPs with presence flags instead of secret material.
  • 400A provider or the public origin is invalid (oidc_config). As text/plain, when the body is not syntactically valid JSON. Body: ErrorJson (application/json); string (text/plain)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The configuration file or the sealed secrets could not be written (oidc_config). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/config' \
    -X PUT \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"enabled": true}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/config' `
    -Method Put `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"enabled": true}'
import requests

response = requests.put(
    "http://127.0.0.1:8787/api/auth/oidc/config",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"enabled": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/config", {
  method: "PUT",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"enabled": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .put("http://127.0.0.1:8787/api/auth/oidc/config")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"enabled": true}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The settings after the change.

{
  "enabled": true,
  "allowed_email_domains": [
    "example.com"
  ],
  "public_origin": "https://books.example.com",
  "issuer_url": "https://books.example.com",
  "detected_origin": "http://localhost:8787",
  "discovery_url": "https://books.example.com/.well-known/openid-configuration",
  "authorization_endpoint": "https://books.example.com/oidc/authorize",
  "token_endpoint": "https://books.example.com/oidc/token",
  "userinfo_endpoint": "https://books.example.com/oidc/userinfo",
  "revocation_endpoint": "https://books.example.com/oidc/revoke",
  "callback_url": "https://books.example.com/api/auth/oidc/callback",
  "providers": [
    {
      "id": "google",
      "name": "Google",
      "preset": "google",
      "issuer": "https://accounts.google.com",
      "client_id": "123456789012-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.apps.googleusercontent.com",
      "scopes": [
        "openid",
        "profile",
        "email"
      ],
      "provision": "allowlist",
      "default_role": "member",
      "role_claim": "groups",
      "role_map": {},
      "link_by_email": true,
      "allowed_email_domains": [
        "example.com"
      ],
      "allowed_emails": [
        "dana@example.com"
      ],
      "allowed_subjects": [
        "248289761001"
      ],
      "apple_team_id": "A1B2C3D4E5",
      "apple_key_id": "K9L8M7N6P5",
      "has_client_secret": true,
      "has_apple_private_key": false,
      "secret_source": "store"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "Operator-facing OIDC broker snapshot; secret material is never included.",
  "required": [
    "enabled",
    "allowed_email_domains",
    "issuer_url",
    "detected_origin",
    "discovery_url",
    "authorization_endpoint",
    "token_endpoint",
    "userinfo_endpoint",
    "revocation_endpoint",
    "callback_url",
    "providers"
  ],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether the broker accepts new authorize starts.",
      "example": true
    },
    "allowed_email_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Broker-wide email domain allowlist applied before per-provider rules.",
      "example": [
        "example.com"
      ]
    },
    "public_origin": {
      "type": [
        "string",
        "null"
      ],
      "description": "Configured `integrations.public_origin` (issuer / callback / invite base).",
      "example": "https://books.example.com"
    },
    "issuer_url": {
      "type": "string",
      "description": "Effective issuer origin (`public_origin`, else this request, else localhost).",
      "example": "https://books.example.com"
    },
    "detected_origin": {
      "type": "string",
      "description": "Origin detected from this request (loopback IPs rewritten to `localhost`).",
      "example": "http://localhost:8787"
    },
    "discovery_url": {
      "type": "string",
      "description": "Absolute OpenID discovery URL (`/.well-known/openid-configuration`).",
      "example": "https://books.example.com/.well-known/openid-configuration"
    },
    "authorization_endpoint": {
      "type": "string",
      "description": "Absolute authorization endpoint (`/oidc/authorize`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/authorize"
    },
    "token_endpoint": {
      "type": "string",
      "description": "Absolute token endpoint (`/oidc/token`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/token"
    },
    "userinfo_endpoint": {
      "type": "string",
      "description": "Absolute userinfo endpoint (`/oidc/userinfo`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/userinfo"
    },
    "revocation_endpoint": {
      "type": "string",
      "description": "Absolute revocation endpoint (`/oidc/revoke`) for Bookclerk-as-IdP.",
      "example": "https://books.example.com/oidc/revoke"
    },
    "callback_url": {
      "type": "string",
      "description": "Absolute `/api/auth/oidc/callback` derived from the effective issuer origin.",
      "example": "https://books.example.com/api/auth/oidc/callback"
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One IdP as shown to an operator (no client secret or Apple PEM).",
        "required": [
          "id",
          "name",
          "client_id",
          "scopes",
          "provision",
          "default_role",
          "role_claim",
          "role_map",
          "link_by_email",
          "allowed_email_domains",
          "allowed_emails",
          "allowed_subjects",
          "has_client_secret",
          "has_apple_private_key",
          "secret_source"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable provider id used in authorize URLs and sealed-row names.",
            "example": "google"
          },
          "name": {
            "type": "string",
            "description": "Operator-facing display name.",
            "example": "Google"
          },
          "preset": {
            "type": [
              "string",
              "null"
            ],
            "description": "Built-in social preset (`google`, `github`, `apple`, `discord`) when not a generic issuer.",
            "example": "google"
          },
          "issuer": {
            "type": [
              "string",
              "null"
            ],
            "description": "OpenID issuer URL for discovery when no social preset applies.",
            "example": "https://accounts.google.com"
          },
          "client_id": {
            "type": "string",
            "description": "OAuth client id registered at the IdP.",
            "example": "123456789012-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.apps.googleusercontent.com"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OAuth scopes requested at authorize.",
            "example": [
              "openid",
              "profile",
              "email"
            ]
          },
          "provision": {
            "type": "string",
            "description": "How a first login becomes a portal user (JIT, mapped role, allowlist, invite-only).",
            "example": "allowlist"
          },
          "default_role": {
            "type": "string",
            "description": "Portal role used when no mapped claim matches (`member` by default).",
            "example": "member"
          },
          "role_claim": {
            "type": "string",
            "description": "Claim name read from id_token/userinfo for role mapping (`groups` by default).",
            "example": "groups"
          },
          "role_map": {
            "type": "object",
            "description": "IdP group/role claim values mapped onto Bookclerk portal roles.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            },
            "example": {}
          },
          "link_by_email": {
            "type": "boolean",
            "description": "When true, a verified email may attach this IdP to an existing user.",
            "example": true
          },
          "allowed_email_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Per-provider email domain allowlist (in addition to the broker-wide list).",
            "example": [
              "example.com"
            ]
          },
          "allowed_emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exact emails permitted under allowlist provision.",
            "example": [
              "dana@example.com"
            ]
          },
          "allowed_subjects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exact IdP subject ids permitted under allowlist provision.",
            "example": [
              "248289761001"
            ]
          },
          "apple_team_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apple Developer team id used to mint the client-secret JWT.",
            "example": "A1B2C3D4E5"
          },
          "apple_key_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apple Sign In key id paired with the sealed private key.",
            "example": "K9L8M7N6P5"
          },
          "has_client_secret": {
            "type": "boolean",
            "description": "Whether a client secret exists in env, TOML, or the sealed store (value never returned).",
            "example": true
          },
          "has_apple_private_key": {
            "type": "boolean",
            "description": "Whether an Apple PEM exists in env, TOML, or the sealed store (PEM never returned).",
            "example": false
          },
          "secret_source": {
            "type": "string",
            "description": "Where the client secret was found: `env`, `config`, `store`, or `none`.",
            "example": "store"
          }
        }
      },
      "description": "Configured IdPs with presence flags instead of secret material."
    }
  }
}

Status 400: A provider or the public origin is invalid (oidc_config). As text/plain, when the body is not syntactically valid JSON.

{
  "error": "oidc_config",
  "message": "public origin must use http or https",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `enabled` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The configuration file or the sealed secrets could not be written (oidc_config).

{
  "error": "oidc_config",
  "message": "failed to write config.toml: Permission denied (os error 13)",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/passkeys

Lists this user's stored passkeys as { id, credential_id } rows.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Responses

  • 200The caller's passkeys. Body: PasskeysResponse (application/json)1 field
    • passkeysarray of PasskeySummaryrequiredThe caller's passkeys, oldest first.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The passkeys could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys' \
    -b 'bookclerk_portal_session=<portalSession>'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys' `
    -WebSession $session
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/passkeys",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys", {
  headers: { Cookie: "bookclerk_portal_session=<portalSession>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/passkeys")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's passkeys.

{
  "passkeys": [
    {
      "id": 4,
      "credential_id": "pQECAyYgASFYIE9ZJ2kLm3nO4pQ5rS6tU7vW8xY9zA0",
      "name": "YubiKey 5C"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/passkeys`.",
  "required": [
    "passkeys"
  ],
  "properties": {
    "passkeys": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One stored passkey.",
        "required": [
          "id",
          "credential_id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Row id, for `DELETE /api/auth/passkeys/{id}`.",
            "example": 4
          },
          "credential_id": {
            "type": "string",
            "description": "Base64url credential id the authenticator reports.",
            "example": "pQECAyYgASFYIE9ZJ2kLm3nO4pQ5rS6tU7vW8xY9zA0"
          },
          "name": {
            "type": "string",
            "description": "Label chosen at registration (`Passkey` when none was given).",
            "example": "YubiKey 5C"
          }
        }
      },
      "description": "The caller's passkeys, oldest first."
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The passkeys could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/passkeys/register/begin

Starts passkey registration (skips reauth only for first local-only setup).

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Request body

application/json: PasskeyReauthBody

  • current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.

Responses

  • 200WebAuthn creation options. Body: PasskeyCreationOptions (application/json)2 fields
    • challenge_idstringrequiredServer-issued challenge id to send back with the attestation; consumed once, five-minute lifetime.
    • publicKeyany JSONrequiredW3C PublicKeyCredentialCreationOptions (relying party, user, challenge, algorithms, excluded credentials), binary fields base64url-encoded.
  • 400The daemon's origin is not a valid WebAuthn relying party (set integrations.public_origin). As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many wrong current_password attempts for this account; try again after the lockout. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The library could not be read, or the challenge could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/register/begin' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/register/begin' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/passkeys/register/begin",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/register/begin", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/passkeys/register/begin")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: WebAuthn creation options.

{
  "challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f",
  "publicKey": {
    "attestation": "none",
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
    "excludeCredentials": [],
    "pubKeyCredParams": [
      {
        "alg": -7,
        "type": "public-key"
      },
      {
        "alg": -257,
        "type": "public-key"
      }
    ],
    "rp": {
      "id": "books.example.com",
      "name": "Bookclerk"
    },
    "timeout": 60000,
    "user": {
      "displayName": "Sam",
      "id": "AAAAAAAAAAAAAAAAAAAABw",
      "name": "sam"
    }
  }
}

Schema:

{
  "type": "object",
  "description": "WebAuthn creation options for `navigator.credentials.create()`, plus the challenge id for the finish step.",
  "required": [
    "challenge_id",
    "publicKey"
  ],
  "properties": {
    "challenge_id": {
      "type": "string",
      "description": "Server-issued challenge id to send back with the attestation; consumed once, five-minute lifetime.",
      "example": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f"
    },
    "publicKey": {
      "description": "W3C PublicKeyCredentialCreationOptions (relying party, user, challenge, algorithms, excluded credentials), binary fields base64url-encoded.",
      "examples": [
        {
          "attestation": "none",
          "authenticatorSelection": {
            "residentKey": "required",
            "userVerification": "preferred"
          },
          "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
          "excludeCredentials": [],
          "pubKeyCredParams": [
            {
              "alg": -7,
              "type": "public-key"
            },
            {
              "alg": -257,
              "type": "public-key"
            }
          ],
          "rp": {
            "id": "books.example.com",
            "name": "Bookclerk"
          },
          "timeout": 60000,
          "user": {
            "displayName": "Sam",
            "id": "AAAAAAAAAAAAAAAAAAAABw",
            "name": "sam"
          }
        }
      ]
    }
  }
}

Status 400: The daemon's origin is not a valid WebAuthn relying party (set integrations.public_origin). As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: current_password: invalid type: integer `1`, expected a string at line 1 column 21

Schema:

A text/plain body: a string.

Status 429: Too many wrong current_password attempts for this account; try again after the lockout.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The library could not be read, or the challenge could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/passkeys/register/finish

Completes registration, stores the passkey, and revokes elevated operator sessions.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Request body

application/json: RegistrationFinish

  • challenge_idstringrequiredServer-issued challenge id (consumed once; 5-minute TTL).
  • credentialany JSONrequiredW3C PublicKeyCredential as the browser serializes it: a registration attestation (response.attestationObject) or an authentication assertion (response.authenticatorData, signature, userHandle), binary fields base64url-encoded.
  • namestring or nullLabel stored with the credential (Passkey when empty).

Responses

  • 200The passkey was stored. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 400The challenge is unknown or expired, the attestation is invalid, or the daemon's origin is not a valid WebAuthn relying party. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The challenge was issued to another user. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409The passkey is already registered. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/register/finish' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/register/finish' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/passkeys/register/finish",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/register/finish", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/passkeys/register/finish")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The passkey was stored.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 400: The challenge is unknown or expired, the attestation is invalid, or the daemon's origin is not a valid WebAuthn relying party. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The challenge was issued to another user. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 409: The passkey is already registered.

{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `challenge_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/passkeys/{id}

Deletes one passkey after recent reauth; 404 when the id is not this user's.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Parameters

  • idpathinteger (int64)requiredPasskey id.

Request body

application/json: PasskeyReauthBody

  • current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.

Responses

  • 200The passkey was deleted. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such passkey for this user. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many wrong current_password attempts for this account; try again after the lockout. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/<id>' \
    -X DELETE \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/<id>' `
    -Method Delete `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/passkeys/<id>",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/<id>", {
  method: "DELETE",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/passkeys/<id>")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The passkey was deleted.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: No such passkey for this user.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: current_password: invalid type: integer `1`, expected a string at line 1 column 21

Schema:

A text/plain body: a string.

Status 429: Too many wrong current_password attempts for this account; try again after the lockout.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/passkeys/login/begin

Rate-limits and starts passkey login; records a failure on any error.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: LoginBegin

  • loginstringrequiredLogin name or email looked up before issuing an authentication challenge.

Responses

  • 200WebAuthn request options. Body: PasskeyRequestOptions (application/json)3 fields
    • challenge_idstringrequiredServer-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.
    • publicKeyany JSONrequiredW3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.
    • mediationstring or nullCredential mediation the daemon asks the browser for; absent unless conditional mediation was requested.
  • 400The daemon's origin is not a valid WebAuthn relying party (set integrations.public_origin). As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401No user has this login name or email. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The user is disabled. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404The user has no usable passkeys. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many failed attempts from this client; try later. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The library could not be read, or the challenge could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/login/begin' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"login": "dana"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/login/begin' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"login": "dana"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/passkeys/login/begin",
    json={"login": "dana"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/login/begin", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"login": "dana"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/passkeys/login/begin")
    .json(&serde_json::json!({"login": "dana"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: WebAuthn request options.

{
  "challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f",
  "publicKey": {
    "allowCredentials": [
      {
        "id": "pQECAyYgASFYIE",
        "type": "public-key"
      }
    ],
    "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
    "rpId": "books.example.com",
    "timeout": 60000,
    "userVerification": "preferred"
  },
  "mediation": "conditional"
}

Schema:

{
  "type": "object",
  "description": "WebAuthn request options for `navigator.credentials.get()`, plus the challenge id for the finish step.",
  "required": [
    "challenge_id",
    "publicKey"
  ],
  "properties": {
    "challenge_id": {
      "type": "string",
      "description": "Server-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.",
      "example": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f"
    },
    "publicKey": {
      "description": "W3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.",
      "examples": [
        {
          "allowCredentials": [
            {
              "id": "pQECAyYgASFYIE",
              "type": "public-key"
            }
          ],
          "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
          "rpId": "books.example.com",
          "timeout": 60000,
          "userVerification": "preferred"
        }
      ]
    },
    "mediation": {
      "type": [
        "string",
        "null"
      ],
      "description": "Credential mediation the daemon asks the browser for; absent unless\nconditional mediation was requested.",
      "example": "conditional"
    }
  }
}

Status 400: The daemon's origin is not a valid WebAuthn relying party (set integrations.public_origin). As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: No user has this login name or email.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The user is disabled.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: The user has no usable passkeys.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `login` at line 1 column 2

Schema:

A text/plain body: a string.

Status 429: Too many failed attempts from this client; try later.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The library could not be read, or the challenge could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/passkeys/login/finish

Verifies the assertion, updates the credential counter, and issues a portal session.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: AssertionFinish

  • challenge_idstringrequiredServer-issued challenge id (consumed once; 5-minute TTL).
  • credentialany JSONrequiredW3C PublicKeyCredential as the browser serializes it: a registration attestation (response.attestationObject) or an authentication assertion (response.authenticatorData, signature, userHandle), binary fields base64url-encoded.

Responses

  • 200Signed in; the response sets the portal session cookie. Body: PortalSessionIssued (application/json)2 fields
    • okbooleanrequiredAlways true on this success path.
    • rolestringrequiredThe user's role (owner, administrator, or member).
  • 400The challenge is unknown or expired, or the daemon's origin is not a valid WebAuthn relying party. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The assertion does not verify, or the credential is not one of the challenged user's. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The user is disabled. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/login/finish' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/login/finish' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/passkeys/login/finish",
    json={"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/login/finish", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/passkeys/login/finish")
    .json(&serde_json::json!({"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Signed in; the response sets the portal session cookie.

{
  "ok": true,
  "role": "member"
}

Schema:

{
  "type": "object",
  "description": "JSON body after a portal session was minted for a first-party user.",
  "required": [
    "ok",
    "role"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "role": {
      "type": "string",
      "description": "The user's role (`owner`, `administrator`, or `member`).",
      "example": "member"
    }
  }
}

Status 400: The challenge is unknown or expired, or the daemon's origin is not a valid WebAuthn relying party. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The assertion does not verify, or the credential is not one of the challenged user's.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The user is disabled.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `challenge_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/passkeys/elevate/begin

Starts Owner elevation; 403 unless the signed-in user is an Owner with passkeys.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Responses

  • 200WebAuthn request options. Body: PasskeyRequestOptions (application/json)3 fields
    • challenge_idstringrequiredServer-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.
    • publicKeyany JSONrequiredW3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.
    • mediationstring or nullCredential mediation the daemon asks the browser for; absent unless conditional mediation was requested.
  • 400The daemon's origin is not a valid WebAuthn relying party (set integrations.public_origin). Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not an Owner. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404The caller has no passkeys. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The library could not be read, or the challenge could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/elevate/begin' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/elevate/begin' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/passkeys/elevate/begin",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/elevate/begin", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/passkeys/elevate/begin")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: WebAuthn request options.

{
  "challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f",
  "publicKey": {
    "allowCredentials": [
      {
        "id": "pQECAyYgASFYIE",
        "type": "public-key"
      }
    ],
    "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
    "rpId": "books.example.com",
    "timeout": 60000,
    "userVerification": "preferred"
  },
  "mediation": "conditional"
}

Schema:

{
  "type": "object",
  "description": "WebAuthn request options for `navigator.credentials.get()`, plus the challenge id for the finish step.",
  "required": [
    "challenge_id",
    "publicKey"
  ],
  "properties": {
    "challenge_id": {
      "type": "string",
      "description": "Server-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.",
      "example": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f"
    },
    "publicKey": {
      "description": "W3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.",
      "examples": [
        {
          "allowCredentials": [
            {
              "id": "pQECAyYgASFYIE",
              "type": "public-key"
            }
          ],
          "challenge": "k9u2Xo3cZ1Qp7mT4vW8yA2bC5dE6fG7hI8jK9lM0nO1",
          "rpId": "books.example.com",
          "timeout": 60000,
          "userVerification": "preferred"
        }
      ]
    },
    "mediation": {
      "type": [
        "string",
        "null"
      ],
      "description": "Credential mediation the daemon asks the browser for; absent unless\nconditional mediation was requested.",
      "example": "conditional"
    }
  }
}

Status 400: The daemon's origin is not a valid WebAuthn relying party (set integrations.public_origin).

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is not an Owner. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: The caller has no passkeys.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The library could not be read, or the challenge could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/passkeys/elevate/finish

Completes Owner elevation only when the assertion is user-verified.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Request body

application/json: AssertionFinish

  • challenge_idstringrequiredServer-issued challenge id (consumed once; 5-minute TTL).
  • credentialany JSONrequiredW3C PublicKeyCredential as the browser serializes it: a registration attestation (response.attestationObject) or an authentication assertion (response.authenticatorData, signature, userHandle), binary fields base64url-encoded.

Responses

  • 200Elevated; the response sets a short-lived operator cookie. Body: Elevated (application/json)3 fields
    • okbooleanrequiredAlways true on this success path.
    • elevatedbooleanrequiredAlways true: the cookie the response sets is an elevated operator session.
    • expires_in_secsinteger (int64)requiredSeconds until the elevated session expires. At least 0.
  • 400The challenge is unknown or expired, or the daemon's origin is not a valid WebAuthn relying party. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in, the assertion does not verify or was not user-verified, or the credential is not the caller's. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is not an Owner, or the challenge was issued to another user. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/passkeys/elevate/finish' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/passkeys/elevate/finish' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/passkeys/elevate/finish",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/passkeys/elevate/finish", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/passkeys/elevate/finish")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({"challenge_id": "6d2f0c1e-8a4b-4f3d-9e7c-5b1a2c3d4e5f", "credential": {"extensions": {}, "id": "pQECAyYgASFYIE", "rawId": "pQECAyYgASFYIE", "response": {"attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViU", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiazl1MlhvM2NaMVFwN21UNHZXOHlBMmJDNWRFNmZHN2hJOGpLOWxNMG5PMSIsIm9yaWdpbiI6Imh0dHBzOi8vYm9va3MuZXhhbXBsZS5jb20ifQ"}, "type": "public-key"}}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Elevated; the response sets a short-lived operator cookie.

{
  "ok": true,
  "elevated": true,
  "expires_in_secs": 900
}

Schema:

{
  "type": "object",
  "description": "JSON body after a successful Owner elevation.",
  "required": [
    "ok",
    "elevated",
    "expires_in_secs"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "elevated": {
      "type": "boolean",
      "description": "Always `true`: the cookie the response sets is an elevated operator session.",
      "example": true
    },
    "expires_in_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds until the elevated session expires.",
      "example": 900,
      "minimum": 0
    }
  }
}

Status 400: The challenge is unknown or expired, or the daemon's origin is not a valid WebAuthn relying party. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in, the assertion does not verify or was not user-verified, or the credential is not the caller's.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is not an Owner, or the challenge was issued to another user. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `challenge_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/totp/login

Completes password+TOTP login and issues a portal session cookie.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: LoginVerify

  • challenge_idstringrequiredServer-issued challenge id (5-minute TTL, single use).
  • codestringrequiredSix-digit authenticator code.

Responses

  • 200Signed in; the response sets the portal session cookie. Body: PortalSessionIssued (application/json)2 fields
    • okbooleanrequiredAlways true on this success path.
    • rolestringrequiredThe user's role (owner, administrator, or member).
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The challenge is unknown or expired, TOTP is off for the user, or the code is wrong (invalid_code); or the challenged user no longer exists (the standard error body). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many failed attempts from this client; try later. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The user or secret could not be read, or the session could not be stored. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/totp/login' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"challenge_id": "2c7e4f0a-9b1d-4e3c-a5f6-7d8e9f0a1b2c", "code": "492817"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/totp/login' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"challenge_id": "2c7e4f0a-9b1d-4e3c-a5f6-7d8e9f0a1b2c", "code": "492817"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/totp/login",
    json={"challenge_id": "2c7e4f0a-9b1d-4e3c-a5f6-7d8e9f0a1b2c", "code": "492817"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/totp/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"challenge_id": "2c7e4f0a-9b1d-4e3c-a5f6-7d8e9f0a1b2c", "code": "492817"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/totp/login")
    .json(&serde_json::json!({"challenge_id": "2c7e4f0a-9b1d-4e3c-a5f6-7d8e9f0a1b2c", "code": "492817"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Signed in; the response sets the portal session cookie.

{
  "ok": true,
  "role": "member"
}

Schema:

{
  "type": "object",
  "description": "JSON body after a portal session was minted for a first-party user.",
  "required": [
    "ok",
    "role"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true` on this success path.",
      "example": true
    },
    "role": {
      "type": "string",
      "description": "The user's role (`owner`, `administrator`, or `member`).",
      "example": "member"
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The challenge is unknown or expired, TOTP is off for the user, or the code is wrong (invalid_code); or the challenged user no longer exists (the standard error body).

{
  "error": "invalid_code",
  "message": "Invalid authenticator code.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `challenge_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 429: Too many failed attempts from this client; try later.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The user or secret could not be read, or the session could not be stored.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/totp/enroll/begin

Starts TOTP enrollment: new pending secret, otpauth URL, and QR SVG.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Request body

application/json: TotpReauthBody

  • current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.

Responses

  • 200A pending secret, its otpauth URL and a QR code SVG. Body: TotpEnrollment (application/json)3 fields
    • secretstringrequiredPending base32 secret, for typing into an app by hand.
    • otpauth_urlstringrequiredotpauth:// URL the QR code encodes.
    • qr_svgstringrequiredThe QR code as an SVG document, ready to inline.
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409TOTP is already on. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many wrong current_password attempts for this account; try again after the lockout. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The secret could not be sealed and stored, or the library could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/totp/enroll/begin' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/totp/enroll/begin' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/totp/enroll/begin",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/totp/enroll/begin", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/totp/enroll/begin")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: A pending secret, its otpauth URL and a QR code SVG.

{
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/Bookclerk:sam?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Bookclerk&algorithm=SHA1&digits=6&period=30",
  "qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 37 37\">…</svg>"
}

Schema:

{
  "type": "object",
  "description": "JSON body after TOTP enrollment began: what the authenticator app needs.",
  "required": [
    "secret",
    "otpauth_url",
    "qr_svg"
  ],
  "properties": {
    "secret": {
      "type": "string",
      "description": "Pending base32 secret, for typing into an app by hand.",
      "example": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP"
    },
    "otpauth_url": {
      "type": "string",
      "description": "`otpauth://` URL the QR code encodes.",
      "example": "otpauth://totp/Bookclerk:sam?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Bookclerk&algorithm=SHA1&digits=6&period=30"
    },
    "qr_svg": {
      "type": "string",
      "description": "The QR code as an SVG document, ready to inline.",
      "example": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 37 37\">…</svg>"
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 409: TOTP is already on.

{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: current_password: invalid type: integer `1`, expected a string at line 1 column 21

Schema:

A text/plain body: a string.

Status 429: Too many wrong current_password attempts for this account; try again after the lockout.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The secret could not be sealed and stored, or the library could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/totp/enroll/finish

Confirms the pending secret with a valid code and sets users.totp_enabled.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Request body

application/json: EnrollFinish

  • codestringrequiredSix-digit code from the authenticator app.

Responses

  • 200TOTP is on. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 400No enrollment is pending; start one first. As text/plain, when the body is not syntactically valid JSON. Body: ApiError (application/json); string (text/plain)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The caller is not signed in (the standard error body), or the code is wrong (invalid_code). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409TOTP is already on. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The pending secret could not be read, or the enrollment could not be confirmed. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/totp/enroll/finish' \
    -X POST \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{"code": "492817"}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/totp/enroll/finish' `
    -Method Post `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{"code": "492817"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/totp/enroll/finish",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={"code": "492817"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/totp/enroll/finish", {
  method: "POST",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({"code": "492817"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/totp/enroll/finish")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({"code": "492817"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: TOTP is on.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 400: No enrollment is pending; start one first. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 401: The caller is not signed in (the standard error body), or the code is wrong (invalid_code).

{
  "error": "invalid_code",
  "message": "Invalid authenticator code.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 409: TOTP is already on.

{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `code` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The pending secret could not be read, or the enrollment could not be confirmed.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/totp

GET /api/auth/totp — whether TOTP is confirmed for this user.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Responses

  • 200Whether TOTP is on for the caller. Body: TotpStatus (application/json)1 field
    • enabledbooleanrequiredWhether an authenticator app is confirmed for the caller.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The user could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/totp' \
    -b 'bookclerk_portal_session=<portalSession>'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/totp' `
    -WebSession $session
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/totp",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/totp", {
  headers: { Cookie: "bookclerk_portal_session=<portalSession>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/totp")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Whether TOTP is on for the caller.

{
  "enabled": true
}

Schema:

{
  "type": "object",
  "description": "JSON body for `GET /api/auth/totp`.",
  "required": [
    "enabled"
  ],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether an authenticator app is confirmed for the caller.",
      "example": true
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The user could not be read.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/totp

Disables TOTP after recent reauth and deletes sealed secrets.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: portalSession

Request body

application/json: TotpReauthBody

  • current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.

Responses

  • 200TOTP is off. Body: OkResponse (application/json)1 field
    • okbooleanrequiredAlways true: a failure answers with an error status instead.
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 429Too many wrong current_password attempts for this account; try again after the lockout. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The library could not be read or written. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/totp' \
    -X DELETE \
    -b 'bookclerk_portal_session=<portalSession>' \
    -H 'Origin: http://127.0.0.1:8787' \
    -H 'Content-Type: application/json' \
    -d '{}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/totp' `
    -Method Delete `
    -WebSession $session `
    -Headers @{ Origin = 'http://127.0.0.1:8787' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/totp",
    headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/totp", {
  method: "DELETE",
  headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/totp")
    .header("Cookie", "bookclerk_portal_session=<portalSession>")
    .header("Origin", "http://127.0.0.1:8787")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: TOTP is off.

{
  "ok": true
}

Schema:

{
  "type": "object",
  "description": "Acknowledgement body (`{\"ok\": true}`) for actions with nothing else to report.",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Always `true`: a failure answers with an error status instead.",
      "example": true
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in, or the session is older than fifteen minutes and current_password is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: current_password: invalid type: integer `1`, expected a string at line 1 column 21

Schema:

A text/plain body: a string.

Status 429: Too many wrong current_password attempts for this account; try again after the lockout.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 500: The library could not be read or written.

{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable); ask again after Retry-After seconds.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/mfa-policy

Current MFA policy (require_second_factor).

Access: The operator, or a signed-in Owner.

Credentials: operatorToken or operatorSession or portalSession

Responses

  • 200Whether a second factor is required. Body: MfaPolicy (application/json)1 field
    • require_second_factorbooleanrequiredWhether every password sign-in must be followed by a passkey or authenticator code.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is neither the operator nor an Owner (forbidden), or must enroll a second factor first (mfa_enrollment_required). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/mfa-policy' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/mfa-policy' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/mfa-policy",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/mfa-policy", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/mfa-policy")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Whether a second factor is required.

{
  "require_second_factor": false
}

Schema:

{
  "type": "object",
  "description": "The host-wide second-factor policy.",
  "required": [
    "require_second_factor"
  ],
  "properties": {
    "require_second_factor": {
      "type": "boolean",
      "description": "Whether every password sign-in must be followed by a passkey or authenticator code.",
      "example": false
    }
  }
}

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is neither the operator nor an Owner (forbidden), or must enroll a second factor first (mfa_enrollment_required).

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PUT /api/auth/mfa-policy

Persists daemon.auth.require_second_factor to config.toml.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Request body

application/json: MfaPolicyPut

  • require_second_factorbooleanrequiredWhen true, password login requires TOTP or the user must use a passkey.

Responses

  • 200The policy after the change. Body: MfaPolicy (application/json)1 field
    • require_second_factorbooleanrequiredWhether every password sign-in must be followed by a passkey or authenticator code.
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The configuration path is unknown or the configuration file could not be written (internal_error). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/mfa-policy' \
    -X PUT \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"require_second_factor": true}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/mfa-policy' `
    -Method Put `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"require_second_factor": true}'
import requests

response = requests.put(
    "http://127.0.0.1:8787/api/auth/mfa-policy",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"require_second_factor": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/mfa-policy", {
  method: "PUT",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"require_second_factor": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .put("http://127.0.0.1:8787/api/auth/mfa-policy")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"require_second_factor": true}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The policy after the change.

{
  "require_second_factor": false
}

Schema:

{
  "type": "object",
  "description": "The host-wide second-factor policy.",
  "required": [
    "require_second_factor"
  ],
  "properties": {
    "require_second_factor": {
      "type": "boolean",
      "description": "Whether every password sign-in must be followed by a passkey or authenticator code.",
      "example": false
    }
  }
}

Status 400: The body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `require_second_factor` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The configuration path is unknown or the configuration file could not be written (internal_error).

{
  "error": "internal_error",
  "message": "failed to write config.toml: Permission denied (os error 13)",
  "status": 500
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/auth/player-passwords

Lists the caller's player passwords.

Access: The operator, or any signed-in user.

Credentials: operatorToken or operatorSession or portalSession

Responses

  • 200The caller's player passwords, newest first. Body: PlayerPasswordsJson (application/json)1 field
    • passwordsarray of PlayerPasswordJsonrequiredThe patron's player passwords, newest first.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is the operator, who has none. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. Body: ErrorMessage or ErrorJson (application/json)
  • 500The library could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/player-passwords' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/player-passwords' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/auth/player-passwords",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/player-passwords", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/auth/player-passwords")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's player passwords, newest first.

{
  "passwords": [
    {
      "id": "8f14e45f-ceea-467f-9a1b-2c3d4e5f6a7b",
      "label": "Phone",
      "created_at": "2026-11-20T09:00:00Z",
      "last_used_at": "2026-11-20T09:05:00Z"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/auth/player-passwords` answer.",
  "required": [
    "passwords"
  ],
  "properties": {
    "passwords": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A player password as Account settings lists it.",
        "required": [
          "id",
          "label",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Its id, for removing it.",
            "example": "8f14e45f-ceea-467f-9a1b-2c3d4e5f6a7b"
          },
          "label": {
            "type": "string",
            "description": "The name the patron gave it.",
            "example": "Phone"
          },
          "created_at": {
            "type": "string",
            "description": "When it was made (RFC 3339).",
            "example": "2026-11-20T09:00:00Z"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When it last signed an app in (RFC 3339), if ever.",
            "example": "2026-11-20T09:05:00Z"
          }
        }
      },
      "description": "The patron's player passwords, newest first."
    }
  }
}

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is the operator, who has none. A signed-in user who must enroll a second factor first gets mfa_enrollment_required.

{
  "error": "mfa_enrollment_required",
  "message": "This server requires a passkey or authenticator app. Set one up to continue, or log out and finish later.",
  "status": 403
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 500: The library could not be read.

{
  "error": "the library could not be read"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/auth/player-passwords

Makes a player password for the caller and shows it once.

Access: The operator, or any signed-in user.

Credentials: operatorToken or operatorSession or portalSession

Request body

application/json: NewPlayerPasswordBody

  • labelstringrequiredA name for it, such as the app or device (1 to 64 bytes once trimmed).

Responses

  • 201The new password; secret is shown this once. Body: NewPlayerPasswordJson (application/json)2 fields
    • passwordPlayerPasswordJsonrequiredThe stored password.
    • secretstringrequiredThe password itself, shown this once: the library keeps only its digest.
  • 400The label is empty or over 64 bytes. As text/plain, when the body is not syntactically valid JSON. Body: ErrorMessage (application/json); string (text/plain)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is the operator, who has none. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorMessage or ErrorJson (application/json)
  • 409The caller already keeps twenty; remove one first. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/player-passwords' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"label": "Phone"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/player-passwords' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"label": "Phone"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/player-passwords",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"label": "Phone"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/player-passwords", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"label": "Phone"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/player-passwords")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"label": "Phone"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 201: The new password; secret is shown this once.

{
  "password": {
    "id": "8f14e45f-ceea-467f-9a1b-2c3d4e5f6a7b",
    "label": "Phone",
    "created_at": "2026-11-20T09:00:00Z",
    "last_used_at": "2026-11-20T09:05:00Z"
  },
  "secret": "7KQ2M-XR4TD-9HWPA-3NEFB"
}

Schema:

{
  "type": "object",
  "description": "`POST /api/auth/player-passwords` answer.",
  "required": [
    "password",
    "secret"
  ],
  "properties": {
    "password": {
      "type": "object",
      "description": "The stored password.",
      "required": [
        "id",
        "label",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Its id, for removing it.",
          "example": "8f14e45f-ceea-467f-9a1b-2c3d4e5f6a7b"
        },
        "label": {
          "type": "string",
          "description": "The name the patron gave it.",
          "example": "Phone"
        },
        "created_at": {
          "type": "string",
          "description": "When it was made (RFC 3339).",
          "example": "2026-11-20T09:00:00Z"
        },
        "last_used_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When it last signed an app in (RFC 3339), if ever.",
          "example": "2026-11-20T09:05:00Z"
        }
      }
    },
    "secret": {
      "type": "string",
      "description": "The password itself, shown this once: the library keeps only its\ndigest.",
      "example": "7KQ2M-XR4TD-9HWPA-3NEFB"
    }
  }
}

Status 400: The label is empty or over 64 bytes. As text/plain, when the body is not syntactically valid JSON.

{
  "error": "label must be 1 to 64 bytes"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is the operator, who has none. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "mfa_enrollment_required",
  "message": "This server requires a passkey or authenticator app. Set one up to continue, or log out and finish later.",
  "status": 403
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 409: The caller already keeps twenty; remove one first.

{
  "error": "too_many_player_passwords"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `label` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

{
  "error": "the library could not be read"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/auth/player-passwords/{id}

Removes one of the caller's player passwords and signs out every app it signed in.

Access: The operator, or any signed-in user.

Credentials: operatorToken or operatorSession or portalSession

Parameters

  • idpathstringrequiredThe password's id.

Responses

  • 204Removed; its apps are signed out. No body.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is the operator, who has none. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorMessage or ErrorJson (application/json)
  • 404No such password of the caller's. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The library could not be written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/player-passwords/<id>' \
    -X DELETE \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/player-passwords/<id>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/auth/player-passwords/<id>",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/player-passwords/<id>", {
  method: "DELETE",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/auth/player-passwords/<id>")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 204: Removed; its apps are signed out. No body.

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is the operator, who has none. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "mfa_enrollment_required",
  "message": "This server requires a passkey or authenticator app. Set one up to continue, or log out and finish later.",
  "status": 403
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 404: No such password of the caller's.

{
  "error": "no such player password"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 500: The library could not be written.

{
  "error": "the library could not be read"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

What the consent page shows.

Access: The operator, or any signed-in user.

Credentials: operatorToken or operatorSession or portalSession

Parameters

  • redirect_uriquerystringrequiredThe return address from /player/auth/openid: the library's mobile-redirect path with the app's address as app.
  • code_challengequerystringrequiredThe PKCE S256 challenge.
  • statequerystringThe app's state.

Responses

  • 200The app asking and the signed-in patron. Body: PlayerConsentPage (application/json)2 fields
    • app_namestringrequiredThe app asking, as the page names it.
    • display_namestring or nullThe signed-in patron's display name.
  • 400The parameters are malformed or name an app the library does not return to (invalid_request). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is the operator. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. Body: ErrorMessage or ErrorJson (application/json)
  • 500The library could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

Example response

POST /api/auth/player-consent

Approves or declines an app's browser sign-in.

Access: The operator, or any signed-in user.

Credentials: operatorToken or operatorSession or portalSession

Request body

application/json: PlayerConsentBody

  • approvebooleanrequiredTrue to let the app sign in; false to decline.

Responses

  • 200Where to send the browser next. Body: PlayerConsentRedirect (application/json)1 field
    • redirectstringrequiredWhere to send the browser: the library's own way back to the app, with a code or the refusal.
  • 400The parameters are malformed or name an app the library does not return to (invalid_request). As text/plain, when the body is not syntactically valid JSON. Body: ErrorMessage (application/json); string (text/plain)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is the operator, or not an active user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorMessage or ErrorJson (application/json)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The code could not be stored. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/player-consent' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"redirect_uri": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/player-consent' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"redirect_uri": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/auth/player-consent",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"redirect_uri": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/player-consent", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"redirect_uri": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/auth/player-consent")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"redirect_uri": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "approve": true}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Where to send the browser next.

{
  "redirect": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth&code=...&state=..."
}

Schema:

{
  "type": "object",
  "description": "`POST /api/auth/player-consent` answer.",
  "required": [
    "redirect"
  ],
  "properties": {
    "redirect": {
      "type": "string",
      "description": "Where to send the browser: the library's own way back to the app,\nwith a code or the refusal.",
      "example": "/player/auth/openid/mobile-redirect?app=absorb%3A%2F%2Foauth&code=...&state=..."
    }
  }
}

Status 400: The parameters are malformed or name an app the library does not return to (invalid_request). As text/plain, when the body is not syntactically valid JSON.

{
  "error": "invalid_request"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller is the operator, or not an active user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "mfa_enrollment_required",
  "message": "This server requires a passkey or authenticator app. Set one up to continue, or log out and finish later.",
  "status": 403
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    }
  ]
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: invalid type: null, expected a map at line 1 column 4

Schema:

A text/plain body: a string.

Status 500: The code could not be stored.

{
  "error": "the library could not be read"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown