Auth
Sign-in, sessions, passkeys, TOTP and the operator's elevation.
Back to the web API reference.
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
application/json: LoginRequest
tokenstringrequiredOperator token from the client; compared in constant time and never persisted.
-
200Signed in; the response sets the operator session cookie. Body:
LoginResponse(application/json)3 fieldsokbooleanrequiredAlwaystrueon this success path.rolestringrequiredIssued role (operatorfor token login).default_viewstringrequiredPost-login SPA landing view from operator preferences (discoveron lookup failure).
- 400The body is not syntactically valid JSON. Body: string (
text/plain) -
401The token is wrong (
unauthorized). Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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-Afterseconds. Body:LoginThrottled(application/json)4 fieldserrorstringrequiredAlwaystoo_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 asRetry-After. At least 0.
-
500The library could not be read. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
Public sign-in picker: operator-token availability, SSO IdPs, integration logins.
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
-
200The sign-in methods this library offers. Body:
SigninMethods(application/json)4 fieldsoperator_tokenbooleanrequiredWhether the operator token may be entered in the SPA (only before an Owner exists).oidcarray ofSigninOidcProviderrequiredEnabled OIDC identity providers, in configuration order.integrationsarray ofSigninIntegrationrequiredIntegrations that accept their own credentials at sign-in.require_second_factorbooleanrequiredWhetherdaemon.auth.require_second_factoris on, so clients can explain the enrollment step.
-
500The library could not be read. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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).
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
-
200A single-use tray ticket. Body:
TrayHandoffPrepareResponse(application/json)2 fieldscodestringrequiredSingle-use loopback handoff code forGET /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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The request did not come straight from loopback. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
429Too many failed attempts from this client; retry after
Retry-Afterseconds. Body:LoginThrottled(application/json)4 fieldserrorstringrequiredAlwaystoo_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 asRetry-After. At least 0.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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.
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
codequerystringPresented handoff code; missing or empty fails closed without consuming the slot.
- 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
-
200Who the caller is (operator, portal user, or impersonation). Body:
AuthMeResponse(application/json)11 fieldsauthenticatedbooleanrequiredWhether the request resolved to an operator, portal, or impersonated session.rolestring or nulloperator,owner,administrator, ormember(legacy clients may still sendportal).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).impersonatingAuthMeImpersonatingor nullPresent when the operator is impersonating a User.portalPortalMeInfoor nullLinked portal identity when the caller is a portal (or impersonated) user.userAuthMeUseror nullFirst-party user when the session is linked to ausersrow.second_factorAuthSecondFactoror 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
authenticatedfalse, so the app can show the sign-in screen. Body:AuthMeResponse(application/json)11 fieldsauthenticatedbooleanrequiredWhether the request resolved to an operator, portal, or impersonated session.rolestring or nulloperator,owner,administrator, ormember(legacy clients may still sendportal).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).impersonatingAuthMeImpersonatingor nullPresent when the operator is impersonating a User.portalPortalMeInfoor nullLinked portal identity when the caller is a portal (or impersonated) user.userAuthMeUseror nullFirst-party user when the session is linked to ausersrow.second_factorAuthSecondFactoror 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: ElevateRequest
passwordstringrequiredOwner account password (re-authentication).
-
200Elevated; the response sets a short-lived operator cookie. Body:
Elevated(application/json)3 fieldsokbooleanrequiredAlwaystrueon this success path.elevatedbooleanrequiredAlwaystrue: 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409The caller is already an operator. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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-Afterseconds. Body:LoginThrottled(application/json)4 fieldserrorstringrequiredAlwaystoo_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 asRetry-After. At least 0.
-
500The password hash could not be read, or the elevated session could not be stored. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
End elevation by revoking the elevated operator session cookie.
Access: The operator (token or session) only.
Credentials: operatorSession
-
200Elevation ended. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: a failure answers with an error status instead.
-
400The session is not an elevated one. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
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.
-
200The first Owner was created. Body:
OwnerBootstrapped(application/json)6 fieldsokbooleanrequiredAlwaystrueon this success path.user_idinteger (int64)requiredusers.idof 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not the operator. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409An Owner or Administrator already exists. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
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 nullTargetusers.idwhen a provisioner sets another user's password.
-
200The password was set and other sessions revoked. Body:
PasswordSet(application/json)2 fieldsokbooleanrequiredAlwaystrueon 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not signed in, or the caller already has a password and
current_passwordis missing or wrong. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such user. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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_passwordattempts for this account; try again after the lockout. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: PasswordLoginRequest
loginstringrequiredLogin name or email.passwordstringrequiredPassword verified against the stored hash; mismatch fails closed and counts toward lockout.
- 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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-Afterseconds. Body:LoginThrottled(application/json)4 fieldserrorstringrequiredAlwaystoo_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 asRetry-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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
Operator (or elevated) session starts impersonating a User.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: ImpersonateRequest
user_idinteger (int64)requiredTargetusers.idto impersonate.
-
200The session now acts as the user. Body:
ImpersonationStarted(application/json)2 fieldsokbooleanrequiredAlwaystrueon 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such user. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
Clear impersonation on the current operator session.
Access: The operator (token or session) only.
Credentials: operatorSession
-
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 fieldokbooleanrequiredAlwaystrue: a failure answers with an error status instead.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The session could not be updated. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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
client_idquerystringrequiredMust be [BRANCH_CLIENT_ID].redirect_uriquerystringrequiredWhere the code goes: loopback or https.response_typequerystringrequiredMust becode.scopequerystringMust be [BRANCH_SCOPE].statequerystringEchoed on the redirect.code_challengequerystringrequiredPKCE S256 challenge.code_challenge_methodquerystringMust beS256.branch_namequerystringThe name the branch asks to join as.shared_branch_offerquerystring1when the joining install offers to join as a shared branch ([bookclerk_node_proto::SHARED_BRANCH_OFFER_PARAM]).
-
200What the consent page shows. Body:
BranchConsentPage(application/json)7 fieldslibrary_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 ofConsentConnectionrequiredThe 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorAnswerorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/auth/branch-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string' \
-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/branch-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string' `
-WebSession $session
import requests
response = requests.get(
"http://127.0.0.1:8787/api/auth/branch-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string",
headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/branch-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string", {
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/branch-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: What the consent page shows.
{
"library_name": "books.example.com",
"branch_name": "Living-room NAS",
"redirect_origin": "http://127.0.0.1:8787",
"enrollment": true,
"user": {
"id": 7,
"display_name": "Sam"
},
"connection": {
"choice": false,
"default": "branch"
},
"connections": [
{
"source": "libro",
"account_id": "sam@example.com",
"label": "Sam",
"travels": true
}
]
}
Schema:
{
"type": "object",
"description": "JSON body for `GET /api/auth/branch-consent`: what the consent page shows.",
"required": [
"library_name",
"branch_name",
"redirect_origin",
"enrollment",
"user",
"connection",
"connections"
],
"properties": {
"library_name": {
"type": "string",
"description": "This library's name.",
"example": "books.example.com"
},
"branch_name": {
"type": "string",
"description": "The name the branch asks to join as.",
"example": "Living-room NAS"
},
"redirect_origin": {
"type": "string",
"description": "Origin of the branch's redirect URI, for the page to name.",
"example": "http://127.0.0.1:8787"
},
"enrollment": {
"type": "boolean",
"description": "Whether this library lets new branches join right now.",
"example": true
},
"user": {
"type": "object",
"description": "The signed-in user the branch would belong to.",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "`users.id`.",
"example": 7
},
"display_name": {
"type": [
"string",
"null"
],
"description": "Display name, when set.",
"example": "Sam"
}
}
},
"connection": {
"anyOf": [
{
"type": "object",
"description": "Only a branch (the user is not an Owner).",
"required": [
"choice",
"default"
],
"properties": {
"choice": {
"type": "boolean",
"description": "Always `false`.",
"example": false
},
"default": {
"type": "string",
"description": "Always `branch`.",
"example": "branch"
}
}
},
{
"type": "object",
"description": "An Owner may pick shared_branch, when it is available.",
"required": [
"choice",
"default",
"shared_branch_available",
"step_up"
],
"properties": {
"choice": {
"type": "boolean",
"description": "Always `true`.",
"example": true
},
"default": {
"type": "string",
"description": "Always `branch`.",
"example": "branch"
},
"shared_branch_available": {
"type": "boolean",
"description": "Whether shared branch may be chosen right now.",
"example": false
},
"shared_branch_reason": {
"type": [
"string",
"null"
],
"description": "Why shared branch is shown disabled, when it is.",
"example": "The joining server already holds library data of its own (or did not offer it), so it can only join as a branch."
},
"step_up": {
"type": "array",
"items": {
"type": "string"
},
"description": "The second factors the Owner can step up with (`totp`, `passkey`).",
"example": [
"passkey"
]
}
}
}
],
"description": "The connection types the page may offer."
},
"connections": {
"type": "array",
"items": {
"type": "object",
"description": "One of the consenting user's store connections, as the consent page\nlists it.",
"required": [
"source",
"account_id",
"travels"
],
"properties": {
"source": {
"type": "string",
"description": "Display alias of the storefront.",
"example": "libro"
},
"account_id": {
"type": "string",
"description": "Store account id.",
"example": "sam@example.com"
},
"label": {
"type": [
"string",
"null"
],
"description": "The account's display label, when it has one.",
"example": "Sam"
},
"travels": {
"type": "boolean",
"description": "True when the connection travels: a shareable storefront's, or a\nsingle-keeper one's that no other branch keeps yet (the branch then\nkeeps its login fresh for this library). False when another branch\nalready keeps it, or it does not fit one join's bundle.",
"example": true
}
}
},
"description": "The user's store connections here, and whether each would travel\nto the branch if the user chooses to bring them."
}
}
}
Status 400: The authorize parameters are invalid (invalid_request).
{
"detail": "the branch needs a name of 1 to 64 characters",
"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 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).
{
"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 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: 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
application/json: BranchConsentBody
approvebooleanrequiredTrue to let the branch join; false to deny.connectionstring or nullbranch(default) orshared_branch.step_upStepUpor 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.
-
200
{redirect}back to the branch. Body:ConsentRedirect(application/json)1 fieldredirectstringrequiredWhere to send the browser: the branch's callback with a code, or witherror=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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 matchingOriginorRefereris refused. Body:NodeRefusal(application/json) -
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 fieldserrorstringrequiredStable 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 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
415The request is not
application/json. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 fieldserrorstringrequiredStable 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 issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorAnswerorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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: 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
-
200Passkey request options. Body:
PasskeyRequestOptions(application/json)3 fieldschallenge_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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 matchingOriginorRefereris refused. Body:ErrorAnswer(application/json) -
404The account has no passkey (
no_passkey). Body:ErrorDetail(application/json)2 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorDetailorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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
client_idquerystringrequiredMust be [CLERK_CLIENT_ID].redirect_uriquerystringrequiredWhere the code goes: loopback or https.response_typequerystringrequiredMust becode.scopequerystringMust be [CLERK_SCOPE].statequerystringEchoed on the redirect.code_challengequerystringrequiredPKCE S256 challenge.code_challenge_methodquerystringMust beS256.clerk_namequerystringThe name the clerk gives itself, shown on the consent page and in the user's session list.
-
200What the consent page shows. Body:
ClerkConsentPage(application/json)4 fieldslibrary_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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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:ErrorAnswerorErrorJson(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 issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorAnswerorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/auth/clerk-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string' \
-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/clerk-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string' `
-WebSession $session
import requests
response = requests.get(
"http://127.0.0.1:8787/api/auth/clerk-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string",
headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/clerk-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string", {
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/clerk-consent?client_id=string&redirect_uri=string&response_type=string&code_challenge=string")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: What the consent page shows.
{
"library_name": "books.example.com",
"clerk_name": "Riley's laptop",
"redirect_origin": "http://127.0.0.1:41923",
"user": {
"id": 7,
"display_name": "Sam"
}
}
Schema:
{
"type": "object",
"description": "JSON body for `GET /api/auth/clerk-consent`: what the consent page shows.",
"required": [
"library_name",
"clerk_name",
"redirect_origin",
"user"
],
"properties": {
"library_name": {
"type": "string",
"description": "This library's name.",
"example": "books.example.com"
},
"clerk_name": {
"type": "string",
"description": "The name the clerk gives itself.",
"example": "Riley's laptop"
},
"redirect_origin": {
"type": "string",
"description": "Origin of the clerk's redirect URI, for the page to name.",
"example": "http://127.0.0.1:41923"
},
"user": {
"type": "object",
"description": "The signed-in user the clerk would sign in as.",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "`users.id`.",
"example": 7
},
"display_name": {
"type": [
"string",
"null"
],
"description": "Display name, when set.",
"example": "Sam"
}
}
}
}
}
Status 400: The authorize parameters are invalid (invalid_request).
{
"detail": "the clerk needs a name of 1 to 64 characters",
"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 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).
{
"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 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 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/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
application/json: ClerkConsentBody
approvebooleanrequiredTrue to let the clerk sign in; false to deny.
-
200
{redirect}back to the clerk. Body:ConsentRedirect(application/json)1 fieldredirectstringrequiredWhere to send the browser: the branch's callback with a code, or witherror=access_denied.
-
400The body or its authorize parameters are invalid (
invalid_request). Body:ErrorDetail(application/json)2 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 matchingOriginorRefereris refused. Body:NodeRefusalorErrorJson(application/json) -
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is larger than 8 KiB. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
415The request is not
application/json. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorDetailorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
-
200Signed out; both session cookies are cleared. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: a failure answers with an error status instead.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200The caller's sessions. Body:
SessionsResponse(application/json)1 fieldsessionsarray ofSessionViewrequiredThe 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 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The sessions could not be read. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
idpathinteger (int64)requiredSession id.
-
200The session was revoked. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: a failure answers with an error status instead.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The session could not be deleted. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
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, orsso:{id}).
-
200The profile after the change. Body:
ProfileChanged(application/json)2 fieldsokbooleanrequiredAlwaystrueon this success path.userAuthMeUserrequiredThe profile after the change, asGET /api/auth/mereports 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). Astext/plain, when the body is not syntactically valid JSON. Body:ErrorJson(application/json); string (text/plain)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409The email is used by another account (
email_in_use). Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200The caller's listing choice. Body:
CatalogListingView(application/json)3 fieldslistedbooleanrequiredThe 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_listedbooleanrequiredtruefor an active Owner: an Owner's books are always listed, solistedhas no effect and the app shows that instead of the toggle.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: CatalogListing
listedbooleanrequiredtrue(the default): the libraries this install joined can see, when they ask, that it can supply the caller's books.falsekeeps them out of those answers; the owner's books are always listed.
-
200The caller's listing choice after the change. Body:
CatalogListingView(application/json)3 fieldslistedbooleanrequiredThe 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_listedbooleanrequiredtruefor an active Owner: an Owner's books are always listed, solistedhas 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 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
image/*: BinaryBody
-
200The avatar was stored. Body:
AvatarChanged(application/json)3 fieldsokbooleanrequiredAlwaystrueon this success path.has_avatarbooleanrequiredWhether an uploaded picture is stored now.avatar_sourcestring or nullPresent only after an upload, alwaysupload; absent after a removal (the stored source is then unchanged unless it wasupload).
-
400The body is empty or not a JPEG, PNG or WebP image. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200The avatar was removed. Body:
AvatarChanged(application/json)3 fieldsokbooleanrequiredAlwaystrueon this success path.has_avatarbooleanrequiredWhether an uploaded picture is stored now.avatar_sourcestring or nullPresent only after an upload, alwaysupload; absent after a removal (the stored source is then unchanged unless it wasupload).
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200Enabled identity providers (id and name). Body:
OidcProvidersResponse(application/json)2 fieldsenabledbooleanrequiredWhether the OIDC broker is switched on at all.providersarray ofSigninOidcProviderrequiredProviders 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)
$ 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?);
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.
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
-
200The caller's linked identities. Body:
LinkedIdentitiesResponse(application/json)1 fieldidentitiesarray ofLinkedIdentityrequiredEvery 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The identities could not be read. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
providerquerystringIdP id to start; omitted when the caller has only one enabled provider.
- 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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-Afterseconds. Browsers get an HTML page; a request that asks for JSON (AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
providerquerystringIdP id to start; omitted when the caller has only one enabled provider.
- 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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-Afterseconds. Browsers get an HTML page; a request that asks for JSON (AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 afterRetry-Afterseconds. Browsers get an HTML page; a request that asks for JSON (AcceptorContent-Type) gets the standard error body. Body: string (text/html);ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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 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
codequerystringAuthorization code to exchange; required unlesserroris set.statequerystringCSRFstatethat must match thebookclerk_oidc_txcookie.errorquerystringIdP-reported deny/error; redirects the browser to/?sso_error=denied.userquerystringApple first-login name/email JSON (form_post only).
- 303Redirects into the app: to
/signed in, to/settingsafter an elevation, or withsso_errornaming 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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 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
application/x-www-form-urlencoded: CallbackParams
codestring or nullAuthorization code to exchange; required unlesserroris set.statestring or nullCSRFstatethat must match thebookclerk_oidc_txcookie.errorstring or nullIdP-reported deny/error; redirects the browser to/?sso_error=denied.userstring or nullApple first-login name/email JSON (form_post only).
- 303Redirects into the app: to
/signed in, to/settingsafter an elevation, or withsso_errornaming 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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 (
AcceptorContent-Type) gets the standard error body. Body:ErrorJson(application/json); string (text/html)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Operator GET: broker settings plus secret-presence flags (never plaintext).
Access: The operator, or a signed-in Owner.
Credentials: operatorToken or operatorSession or portalSession
-
200Broker settings, with secrets as presence flags. Body:
OidcConfigResponse(application/json)12 fieldsenabledbooleanrequiredWhether the broker accepts new authorize starts.allowed_email_domainsarray of stringrequiredBroker-wide email domain allowlist applied before per-provider rules.public_originstring or nullConfiguredintegrations.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 tolocalhost).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/callbackderived from the effective issuer origin.providersarray ofOidcProviderViewrequiredConfigured IdPs with presence flags instead of secret material.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Operator-only PUT: writes next-generation sealed secrets, then publishes config.toml.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: OidcConfigPut
enabledbooleanrequiredWhether the broker should accept authorize starts after this write.allowed_email_domainsarray of stringReplacement broker-wide email domain allowlist.providersarray ofOidcProviderPutFull replacement list of IdPs (omitted secrets keep the previous generation).public_originstring or nullintegrations.public_origin. Omit to leave unchanged; empty string clears.
-
200The settings after the change. Body:
OidcConfigResponse(application/json)12 fieldsenabledbooleanrequiredWhether the broker accepts new authorize starts.allowed_email_domainsarray of stringrequiredBroker-wide email domain allowlist applied before per-provider rules.public_originstring or nullConfiguredintegrations.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 tolocalhost).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/callbackderived from the effective issuer origin.providersarray ofOidcProviderViewrequiredConfigured IdPs with presence flags instead of secret material.
-
400A provider or the public origin is invalid (
oidc_config). Astext/plain, when the body is not syntactically valid JSON. Body:ErrorJson(application/json); string (text/plain)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200The caller's passkeys. Body:
PasskeysResponse(application/json)1 fieldpasskeysarray ofPasskeySummaryrequiredThe caller's passkeys, oldest first.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The passkeys could not be read. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: PasskeyReauthBody
current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.
-
200WebAuthn creation options. Body:
PasskeyCreationOptions(application/json)2 fieldschallenge_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). Astext/plain, when the body is not syntactically valid JSON. Body:ApiError(application/json); string (text/plain)3 fieldserrorstringrequiredStable 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_passwordis missing or wrong. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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_passwordattempts for this account; try again after the lockout. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
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 (Passkeywhen empty).
-
200The passkey was stored. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409The passkey is already registered. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
idpathinteger (int64)requiredPasskey id.
application/json: PasskeyReauthBody
current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.
-
200The passkey was deleted. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: 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_passwordis missing or wrong. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such passkey for this user. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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_passwordattempts for this account; try again after the lockout. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The library could not be read or written. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: LoginBegin
loginstringrequiredLogin name or email looked up before issuing an authentication challenge.
-
200WebAuthn request options. Body:
PasskeyRequestOptions(application/json)3 fieldschallenge_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). Astext/plain, when the body is not syntactically valid JSON. Body:ApiError(application/json); string (text/plain)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401No user has this login name or email. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The user is disabled. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404The user has no usable passkeys. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
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.
-
200Signed in; the response sets the portal session cookie. Body:
PortalSessionIssued(application/json)2 fieldsokbooleanrequiredAlwaystrueon this success path.rolestringrequiredThe user's role (owner,administrator, ormember).
-
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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The user is disabled. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
-
200WebAuthn request options. Body:
PasskeyRequestOptions(application/json)3 fieldschallenge_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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404The caller has no passkeys. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
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.
-
200Elevated; the response sets a short-lived operator cookie. Body:
Elevated(application/json)3 fieldsokbooleanrequiredAlwaystrueon this success path.elevatedbooleanrequiredAlwaystrue: 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: LoginVerify
challenge_idstringrequiredServer-issued challenge id (5-minute TTL, single use).codestringrequiredSix-digit authenticator code.
-
200Signed in; the response sets the portal session cookie. Body:
PortalSessionIssued(application/json)2 fieldsokbooleanrequiredAlwaystrueon this success path.rolestringrequiredThe user's role (owner,administrator, ormember).
- 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
application/json: TotpReauthBody
current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.
-
200A pending secret, its otpauth URL and a QR code SVG. Body:
TotpEnrollment(application/json)3 fieldssecretstringrequiredPending 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_passwordis missing or wrong. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409TOTP is already on. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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_passwordattempts for this account; try again after the lockout. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: EnrollFinish
codestringrequiredSix-digit code from the authenticator app.
-
200TOTP is on. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: 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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409TOTP is already on. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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 — 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
-
200Whether TOTP is on for the caller. Body:
TotpStatus(application/json)1 fieldenabledbooleanrequiredWhether an authenticator app is confirmed for the caller.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The user could not be read. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: TotpReauthBody
current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.
-
200TOTP is off. Body:
OkResponse(application/json)1 fieldokbooleanrequiredAlwaystrue: 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_passwordis missing or wrong. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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_passwordattempts for this account; try again after the lockout. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The library could not be read or written. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 afterRetry-Afterseconds. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Current MFA policy (require_second_factor).
Access: The operator, or a signed-in Owner.
Credentials: operatorToken or operatorSession or portalSession
-
200Whether a second factor is required. Body:
MfaPolicy(application/json)1 fieldrequire_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 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Persists daemon.auth.require_second_factor to config.toml.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: MfaPolicyPut
require_second_factorbooleanrequiredWhen true, password login requires TOTP or the user must use a passkey.
-
200The policy after the change. Body:
MfaPolicy(application/json)1 fieldrequire_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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Lists the caller's player passwords.
Access: The operator, or any signed-in user.
Credentials: operatorToken or operatorSession or portalSession
-
200The caller's player passwords, newest first. Body:
PlayerPasswordsJson(application/json)1 fieldpasswordsarray ofPlayerPasswordJsonrequiredThe patron's player passwords, newest first.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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:ErrorMessageorErrorJson(application/json) -
500The library could not be read. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
application/json: NewPlayerPasswordBody
labelstringrequiredA name for it, such as the app or device (1 to 64 bytes once trimmed).
-
201The new password;
secretis shown this once. Body:NewPlayerPasswordJson(application/json)2 fieldspasswordPlayerPasswordJsonrequiredThe 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 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 matchingOriginorRefereris refused. Body:ErrorMessageorErrorJson(application/json) -
409The caller already keeps twenty; remove one first. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 fielderrorstringrequiredWhat 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
idpathstringrequiredThe password's id.
- 204Removed; its apps are signed out. No body.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 matchingOriginorRefereris refused. Body:ErrorMessageorErrorJson(application/json) -
404No such password of the caller's. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The library could not be written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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
redirect_uriquerystringrequiredThe return address from/player/auth/openid: the library's mobile-redirect path with the app's address asapp.code_challengequerystringrequiredThe PKCE S256 challenge.statequerystringThe app's state.
-
200The app asking and the signed-in patron. Body:
PlayerConsentPage(application/json)2 fieldsapp_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 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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:ErrorMessageorErrorJson(application/json) -
500The library could not be read. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ curl 'http://127.0.0.1:8787/api/auth/player-consent?redirect_uri=string&code_challenge=string' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/player-consent?redirect_uri=string&code_challenge=string' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/auth/player-consent?redirect_uri=string&code_challenge=string",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/player-consent?redirect_uri=string&code_challenge=string", {
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-consent?redirect_uri=string&code_challenge=string")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The app asking and the signed-in patron.
{
"app_name": "Absorb",
"display_name": "Riley"
}
Schema:
{
"type": "object",
"description": "`GET /api/auth/player-consent` answer: what the consent page shows.",
"required": [
"app_name"
],
"properties": {
"app_name": {
"type": "string",
"description": "The app asking, as the page names it.",
"example": "Absorb"
},
"display_name": {
"type": [
"string",
"null"
],
"description": "The signed-in patron's display name.",
"example": "Riley"
}
}
}
Status 400: The parameters are malformed or name an app the library does not return to (invalid_request).
{
"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. 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.
Approves or declines an app's browser sign-in.
Access: The operator, or any signed-in user.
Credentials: operatorToken or operatorSession or portalSession
application/json: PlayerConsentBody
approvebooleanrequiredTrue to let the app sign in; false to decline.
-
200Where to send the browser next. Body:
PlayerConsentRedirect(application/json)1 fieldredirectstringrequiredWhere 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). Astext/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 matchingOriginorRefereris refused. Body:ErrorMessageorErrorJson(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 fielderrorstringrequiredWhat 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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