Clerk sign-in

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

Last updated View as Markdown

A clerk's sign-in as a person: redeem an approved code for a session token.

Back to the web API reference.

POST /api/clerk/v1/token

POST /api/clerk/v1/token: redeem an approved clerk sign-in for a session token. The code is spent by any attempt, matching or not.

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

Credentials: none

Request body

application/json: ClerkTokenRequest

  • codestringrequiredThe single-use code from the redirect.
  • code_verifierstringrequiredThe PKCE verifier whose S256 challenge the authorize request sent.
  • redirect_uristringrequiredThe redirect URI the authorize request named.

Responses

  • 200The session token (shown once), this library's id, the signed-in user and how long the session stays signed in unused. Body: ClerkTokenAnswer (application/json)4 fields
    • tokenstringrequiredThe session token, sent as Authorization: Bookclerk-Clerk <token>. Shown once; the library keeps only its hash.
    • library_idstringrequiredThe library id.
    • userClerkUserrequiredThe signed-in person on that library.
    • idle_secsinteger (int64)requiredSeconds the session stays signed in unused; each use resets it.
  • 400The body is not a token request (invalid_request). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason), or the code does not redeem: blank, unknown, used, expired, another client's, a wrong verifier or redirect URI, or the user is no longer active (sign_in_refused). A write sent with a session cookie but without a matching Origin or Referer is refused. Body: NodeRefusal (application/json)
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 413The body is larger than 8 KiB. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The request is not application/json. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The sign-in could not be read or recorded; try again (unavailable). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/clerk/v1/token' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"code": "q8Zl0m3VnS2xR7bW4cYd1eTf6gUh9iJk5LoNpQrStUv", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/clerk/v1/token' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"code": "q8Zl0m3VnS2xR7bW4cYd1eTf6gUh9iJk5LoNpQrStUv", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/clerk/v1/token",
    json={"code": "q8Zl0m3VnS2xR7bW4cYd1eTf6gUh9iJk5LoNpQrStUv", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/clerk/v1/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"code": "q8Zl0m3VnS2xR7bW4cYd1eTf6gUh9iJk5LoNpQrStUv", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/clerk/v1/token")
    .json(&serde_json::json!({"code": "q8Zl0m3VnS2xR7bW4cYd1eTf6gUh9iJk5LoNpQrStUv", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/clerk/callback"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The session token (shown once), this library's id, the signed-in user and how long the session stays signed in unused.

{
  "token": "Zm9vYmFyYmF6cXV4cXV1eGNvcmdlZ3JhdWx0Z2FycGx5",
  "library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "user": {
    "id": 7,
    "display_name": "Riley"
  },
  "idle_secs": 7776000
}

Schema:

{
  "type": "object",
  "description": "`POST /api/clerk/v1/token` answer.",
  "required": [
    "token",
    "library_id",
    "user",
    "idle_secs"
  ],
  "properties": {
    "token": {
      "type": "string",
      "description": "The session token, sent as `Authorization: Bookclerk-Clerk <token>`.\nShown once; the library keeps only its hash.",
      "example": "Zm9vYmFyYmF6cXV4cXV1eGNvcmdlZ3JhdWx0Z2FycGx5"
    },
    "library_id": {
      "type": "string",
      "description": "The library id.",
      "example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "user": {
      "type": "object",
      "description": "The signed-in person on that library.",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "The user's id on the library.",
          "example": 7
        },
        "display_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's display name on the library, when set.",
          "example": "Riley"
        }
      }
    },
    "idle_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Seconds the session stays signed in unused; each use resets it.",
      "example": 7776000
    }
  }
}

Status 400: The body is not a token request (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 403: The connection failed the transport policy (transport_insecure, with the check in reason), or the code does not redeem: blank, unknown, used, expired, another client's, a wrong verifier or redirect URI, or the user is no longer active (sign_in_refused). A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "sign_in_refused"
}

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 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 sign-in could not be read or recorded; try again (unavailable).

{
  "error": "unavailable"
}

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 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/clerk/v1/connect

GET /api/clerk/v1/connect: upgrade to the clerk socket after the transport check and the library card.

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

Credentials: clerkToken

Responses

  • 101Switching to the clerk socket: hello and changed frames name the topics that changed, each books frame is answered with one page of the card's person's books (books.page), and each copy.grant frame with the library's copy of that edition and a one-hour token for GET /api/copies/v1/{copy_id}/files/{index} (copy.granted). An ask that is not answered gets an error frame instead: invalid for a frame the library cannot read, unavailable when it cannot answer just now, and for copy.grant not_found when the person may not take that edition or the library holds no copy of it. No body.
  • 400The request does not offer the bookclerk-clerk.v1 subprotocol (subprotocol_required). Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401No library card, or the card is not signed in (unauthorized). Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The transport is not allowed (transport_insecure), or the card's person must enroll a second factor first (mfa_enrollment_required). Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404The node API is not mounted here (node_api_unmounted). Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503The card could not be checked yet (session_check_unavailable), or too many clerk sockets are open (clerk_sockets_busy); retry after Retry-After seconds. Body: ErrorMessage or ErrorJson (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/clerk/v1/connect' \
    -H 'Authorization: Bookclerk-Clerk <token>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/clerk/v1/connect' `
    -Headers @{ Authorization = 'Bookclerk-Clerk <token>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/clerk/v1/connect",
    headers={"Authorization": "Bookclerk-Clerk <token>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/clerk/v1/connect", {
  headers: { Authorization: "Bookclerk-Clerk <token>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/clerk/v1/connect")
    .header("Authorization", "Bookclerk-Clerk <token>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 101: Switching to the clerk socket: hello and changed frames name the topics that changed, each books frame is answered with one page of the card's person's books (books.page), and each copy.grant frame with the library's copy of that edition and a one-hour token for GET /api/copies/v1/{copy_id}/files/{index} (copy.granted). An ask that is not answered gets an error frame instead: invalid for a frame the library cannot read, unavailable when it cannot answer just now, and for copy.grant not_found when the person may not take that edition or the library holds no copy of it. No body.

Status 400: The request does not offer the bookclerk-clerk.v1 subprotocol (subprotocol_required).

{
  "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 library card, or the card is not signed in (unauthorized).

{
  "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 transport is not allowed (transport_insecure), or the card's person 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": "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 node API is not mounted here (node_api_unmounted).

{
  "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 503: The card could not be checked yet (session_check_unavailable), or too many clerk sockets are open (clerk_sockets_busy); retry after Retry-After seconds.

{
  "error": "clerk_sockets_busy"
}

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 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