OIDC provider
Bookclerk as an OpenID Connect provider for other apps.
Back to the web API reference.
Serves the OIDC discovery document for registered clients.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
-
200The OIDC discovery document. Body:
DiscoveryDocument(application/json)12 fieldsissuerstringrequiredIssuer origin used asissin minted JWTs (public_originor loopback).authorization_endpointstringrequiredAbsolute URL of the authorization endpoint (/oidc/authorize).token_endpointstringrequiredAbsolute URL of the token endpoint (/oidc/token).userinfo_endpointstringrequiredAbsolute URL of the userinfo endpoint (/oidc/userinfo).revocation_endpointstringrequiredAbsolute URL of the refresh-token revocation endpoint (/oidc/revoke).response_types_supportedarray of stringrequiredSupportedresponse_typevalues; this server only issuescode.grant_types_supportedarray of stringrequiredSupported token grants:authorization_codeandrefresh_token.code_challenge_methods_supportedarray of stringrequiredPKCE methods; only S256 is accepted (plainis rejected).scopes_supportedarray of stringrequiredScopes advertised to clients (openid,profile, andemail).subject_types_supportedarray of stringrequiredSubject identifier types; only public (stable user id) is used.id_token_signing_alg_values_supportedarray of stringrequiredID-token signing algorithms; tokens are HS256 with a derived key.token_endpoint_auth_methods_supportedarray of stringrequiredClient auth methods: public PKCE (none) orclient_secret_post.
$ curl 'http://127.0.0.1:8787/.well-known/openid-configuration'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/.well-known/openid-configuration'
import requests
response = requests.get("http://127.0.0.1:8787/.well-known/openid-configuration")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/.well-known/openid-configuration");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/.well-known/openid-configuration").await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The OIDC discovery document.
{
"issuer": "https://books.example.com",
"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",
"response_types_supported": [
"code"
],
"grant_types_supported": [
"authorization_code",
"refresh_token"
],
"code_challenge_methods_supported": [
"S256"
],
"scopes_supported": [
"openid",
"profile",
"email"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"HS256"
],
"token_endpoint_auth_methods_supported": [
"none",
"client_secret_post"
]
}
Schema:
{
"type": "object",
"description": "OIDC discovery document served at `/.well-known/openid-configuration`.",
"required": [
"issuer",
"authorization_endpoint",
"token_endpoint",
"userinfo_endpoint",
"revocation_endpoint",
"response_types_supported",
"grant_types_supported",
"code_challenge_methods_supported",
"scopes_supported",
"subject_types_supported",
"id_token_signing_alg_values_supported",
"token_endpoint_auth_methods_supported"
],
"properties": {
"issuer": {
"type": "string",
"description": "Issuer origin used as `iss` in minted JWTs (`public_origin` or loopback).",
"example": "https://books.example.com"
},
"authorization_endpoint": {
"type": "string",
"description": "Absolute URL of the authorization endpoint (`/oidc/authorize`).",
"example": "https://books.example.com/oidc/authorize"
},
"token_endpoint": {
"type": "string",
"description": "Absolute URL of the token endpoint (`/oidc/token`).",
"example": "https://books.example.com/oidc/token"
},
"userinfo_endpoint": {
"type": "string",
"description": "Absolute URL of the userinfo endpoint (`/oidc/userinfo`).",
"example": "https://books.example.com/oidc/userinfo"
},
"revocation_endpoint": {
"type": "string",
"description": "Absolute URL of the refresh-token revocation endpoint (`/oidc/revoke`).",
"example": "https://books.example.com/oidc/revoke"
},
"response_types_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported `response_type` values; this server only issues `code`.",
"example": [
"code"
]
},
"grant_types_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported token grants: `authorization_code` and `refresh_token`.",
"example": [
"authorization_code",
"refresh_token"
]
},
"code_challenge_methods_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "PKCE methods; only S256 is accepted (`plain` is rejected).",
"example": [
"S256"
]
},
"scopes_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scopes advertised to clients (`openid`, `profile`, and `email`).",
"example": [
"openid",
"profile",
"email"
]
},
"subject_types_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "Subject identifier types; only public (stable user id) is used.",
"example": [
"public"
]
},
"id_token_signing_alg_values_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "ID-token signing algorithms; tokens are HS256 with a derived key.",
"example": [
"HS256"
]
},
"token_endpoint_auth_methods_supported": {
"type": "array",
"items": {
"type": "string"
},
"description": "Client auth methods: public PKCE (`none`) or `client_secret_post`.",
"example": [
"none",
"client_secret_post"
]
}
}
}
Starts the authorization-code flow; unauthenticated users are sent to SPA login.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
client_idquerystringrequiredRegistered OIDC client id (must exist in the library store).redirect_uriquerystringrequiredRedirect URI; must match a URI registered for the client.response_typequerystringrequiredOAuthresponse_type; onlycodeis accepted.scopequerystringSpace-separated scopes; defaults toopenid profilewhen omitted.statequerystringOpaque CSRF value echoed back on the redirect.code_challengequerystringrequiredPKCE S256 challenge (base64url SHA-256 of the verifier).code_challenge_methodquerystringPKCE method; omitted is treated asplainand then rejected.
- 303A
bookclerk-branchrequest is sent to the SPA consent page/join/approve, and abookclerk-clerkrequest to/clerk/approve. No body. - 307Redirects to sign-in (no user session) or to the client with a code. No body.
-
400The request is invalid. Browsers get an HTML page; a request that asks for JSON (
AcceptorContent-Type) gets the standard error body. A query string that cannot be parsed gets a plain-text line. Body:ErrorJson(application/json); string (text/html); 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.
-
403An operator token was sent, or the user is disabled. 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 client or the session could not be read, or the code 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.
$ curl 'http://127.0.0.1:8787/oidc/authorize?client_id=string&redirect_uri=string&response_type=string&code_challenge=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/oidc/authorize?client_id=string&redirect_uri=string&response_type=string&code_challenge=string'
import requests
response = requests.get("http://127.0.0.1:8787/oidc/authorize?client_id=string&redirect_uri=string&response_type=string&code_challenge=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/oidc/authorize?client_id=string&redirect_uri=string&response_type=string&code_challenge=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/oidc/authorize?client_id=string&redirect_uri=string&response_type=string&code_challenge=string").await?;
println!("{} {}", response.status(), response.text().await?);
Status 303: A bookclerk-branch request is sent to the SPA consent page /join/approve, and a bookclerk-clerk request to /clerk/approve. No body.
Status 307: Redirects to sign-in (no user session) or to the client with a code. No body.
Status 400: The request is invalid. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. A query string that cannot be parsed gets a plain-text line.
{
"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: An operator token was sent, or the user is disabled. 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 500: The client or the session could not be read, or the code 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
}
}
}
Completes consent: deny redirects with access_denied, grant issues a code.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
application/x-www-form-urlencoded: ConsentBody
client_idstringrequiredRegistered OIDC client id (must exist in the library store).redirect_uristringrequiredRedirect URI; must match a URI registered for the client.response_typestringrequiredOAuthresponse_type; onlycodeis accepted.scopestring or nullSpace-separated scopes; defaults toopenid profilewhen omitted.statestring or nullOpaque CSRF value echoed back on the redirect.code_challengestringrequiredPKCE S256 challenge (base64url SHA-256 of the verifier).code_challenge_methodstring or nullPKCE method; omitted is treated asplainand then rejected.consentstring or nulldenyaborts withaccess_denied; any other value proceeds to issue a code.
- 307Redirects to the client with a code or
access_denied. No body. -
400The request is invalid. 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.
-
403An operator token was sent, or the user is disabled. 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 client or the session could not be read, or the code 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.
$ curl 'http://127.0.0.1:8787/oidc/authorize' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787' \
-d 'client_id=audiobookshelf&redirect_uri=https%3A%2F%2Fabs.example.com%2Fauth%2Fopenid%2Fcallback&response_type=code&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'
$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/oidc/authorize' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' } `
-ContentType 'application/x-www-form-urlencoded' `
-Body 'client_id=audiobookshelf&redirect_uri=https%3A%2F%2Fabs.example.com%2Fauth%2Fopenid%2Fcallback&response_type=code&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'
import requests
response = requests.post(
"http://127.0.0.1:8787/oidc/authorize",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
data={"client_id": "audiobookshelf", "redirect_uri": "https://abs.example.com/auth/openid/callback", "response_type": "code", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/oidc/authorize", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787" },
body: new URLSearchParams("client_id=audiobookshelf&redirect_uri=https%3A%2F%2Fabs.example.com%2Fauth%2Fopenid%2Fcallback&response_type=code&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/oidc/authorize")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.form(&[("client_id", "audiobookshelf"), ("redirect_uri", "https://abs.example.com/auth/openid/callback"), ("response_type", "code"), ("code_challenge", "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM")])
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 307: Redirects to the client with a code or access_denied. No body.
Status 400: The request is invalid. 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: An operator token was sent, or the user is disabled. 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 500: The client or the session could not be read, or the code 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
}
}
}
Dispatches token grants. Every refusal is an RFC 6749 §5.2 JSON body
([TokenError]), never the branded error page, so a client library can
tell invalid_grant from invalid_client.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
application/x-www-form-urlencoded: TokenForm
grant_typestringrequiredGrant:authorization_codeorrefresh_token; anything else is 400.codestring or nullAuthorization code from the redirect (authorization_codegrant).redirect_uristring or nullMust match the URI bound to the consumed authorization code.client_idstring or nullClient id; required for code exchange, optional (but checked) on refresh.client_secretstring or nullClient secret for confidential clients (client_secret_post).code_verifierstring or nullPKCE verifier; SHA-256 must match the stored challenge.refresh_tokenstring or nullRefresh token to rotate (refresh_tokengrant).
-
200Tokens. Body:
TokenResponse(application/json)6 fieldsaccess_tokenstringrequiredHS256 JWT access token bound to the User (token_use=access).token_typestringrequiredAlwaysBearerfor this server.expires_ininteger (int64)requiredAccess-token lifetime in seconds (same as [ACCESS_TTL_SECS]).refresh_tokenstring or nullOpaque refresh token when the client is allowed to receive one.id_tokenstringrequiredHS256 ID token; profile/email claims follow the granted scope.scopestringrequiredSpace-separated scopes granted to this token pair.
-
400The request is malformed (
invalid_request), the code, refresh token or PKCE verifier is invalid, expired or already used, or the token's user is disabled (invalid_grant), or the grant type is not supported (unsupported_grant_type). Body:TokenError(application/json)2 fieldserrorTokenErrorCoderequiredWhat went wrong, as a client library branches on it.error_descriptionstring or nullA sentence for the person debugging the client; never a secret or a token.
-
401The client is unknown or disabled, or its secret is wrong (
invalid_client). Body:TokenError(application/json)2 fieldserrorTokenErrorCoderequiredWhat went wrong, as a client library branches on it.error_descriptionstring or nullA sentence for the person debugging the client; never a secret or a token.
-
500The code, the token or the user could not be read or stored (
server_error). Body:TokenError(application/json)2 fieldserrorTokenErrorCoderequiredWhat went wrong, as a client library branches on it.error_descriptionstring or nullA sentence for the person debugging the client; never a secret or a token.
$ curl 'http://127.0.0.1:8787/oidc/token' \
-X POST \
-d 'grant_type=authorization_code'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/oidc/token' `
-Method Post `
-ContentType 'application/x-www-form-urlencoded' `
-Body 'grant_type=authorization_code'
import requests
response = requests.post(
"http://127.0.0.1:8787/oidc/token",
data={"grant_type": "authorization_code"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/oidc/token", {
method: "POST",
body: new URLSearchParams("grant_type=authorization_code"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/oidc/token")
.form(&[("grant_type", "authorization_code")])
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Tokens.
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3IiwidG9rZW5fdXNlIjoiYWNjZXNzIn0.3x9Y…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3IiwibmFtZSI6IkRhbmEgUmVhZGVyIn0.Q2r8…",
"scope": "openid profile email"
}
Schema:
{
"type": "object",
"description": "Successful token-endpoint JSON (access, optional refresh, and ID tokens).",
"required": [
"access_token",
"token_type",
"expires_in",
"id_token",
"scope"
],
"properties": {
"access_token": {
"type": "string",
"description": "HS256 JWT access token bound to the User (`token_use=access`).",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3IiwidG9rZW5fdXNlIjoiYWNjZXNzIn0.3x9Y…"
},
"token_type": {
"type": "string",
"description": "Always `Bearer` for this server.",
"example": "Bearer"
},
"expires_in": {
"type": "integer",
"format": "int64",
"description": "Access-token lifetime in seconds (same as [`ACCESS_TTL_SECS`]).",
"example": 3600
},
"refresh_token": {
"type": [
"string",
"null"
],
"description": "Opaque refresh token when the client is allowed to receive one.",
"example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
},
"id_token": {
"type": "string",
"description": "HS256 ID token; profile/email claims follow the granted scope.",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3IiwibmFtZSI6IkRhbmEgUmVhZGVyIn0.Q2r8…"
},
"scope": {
"type": "string",
"description": "Space-separated scopes granted to this token pair.",
"example": "openid profile email"
}
}
}
Status 400: The request is malformed (invalid_request), the code, refresh token or PKCE verifier is invalid, expired or already used, or the token's user is disabled (invalid_grant), or the grant type is not supported (unsupported_grant_type).
{
"error": "invalid_grant",
"error_description": "The authorization code is invalid, expired or already used."
}
Schema:
{
"type": "object",
"description": "A token-endpoint refusal as RFC 6749 §5.2 writes it: JSON with an\n`error` code and a human-readable `error_description`, sent with\n`Cache-Control: no-store`.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as a client library branches on it.",
"enum": [
"invalid_request",
"invalid_client",
"invalid_grant",
"unsupported_grant_type",
"server_error"
]
},
"error_description": {
"type": [
"string",
"null"
],
"description": "A sentence for the person debugging the client; never a secret or\na token.",
"example": "The authorization code is invalid, expired or already used."
}
}
}
Status 401: The client is unknown or disabled, or its secret is wrong (invalid_client).
{
"error": "invalid_client",
"error_description": "The client could not be authenticated."
}
Schema:
{
"type": "object",
"description": "A token-endpoint refusal as RFC 6749 §5.2 writes it: JSON with an\n`error` code and a human-readable `error_description`, sent with\n`Cache-Control: no-store`.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as a client library branches on it.",
"enum": [
"invalid_request",
"invalid_client",
"invalid_grant",
"unsupported_grant_type",
"server_error"
]
},
"error_description": {
"type": [
"string",
"null"
],
"description": "A sentence for the person debugging the client; never a secret or\na token.",
"example": "The authorization code is invalid, expired or already used."
}
}
}
Status 500: The code, the token or the user could not be read or stored (server_error).
{
"error": "server_error",
"error_description": "The token could not be issued. Try again."
}
Schema:
{
"type": "object",
"description": "A token-endpoint refusal as RFC 6749 §5.2 writes it: JSON with an\n`error` code and a human-readable `error_description`, sent with\n`Cache-Control: no-store`.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as a client library branches on it.",
"enum": [
"invalid_request",
"invalid_client",
"invalid_grant",
"unsupported_grant_type",
"server_error"
]
},
"error_description": {
"type": [
"string",
"null"
],
"description": "A sentence for the person debugging the client; never a secret or\na token.",
"example": "The authorization code is invalid, expired or already used."
}
}
}
Returns sub / name / preferred_username for a valid access JWT.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: oidcAccessToken
-
200Claims for the token's user. Body:
UserinfoResponse(application/json)5 fieldssubstringrequiredSubject: the Bookclerkusers.idas a string.namestring or nullDisplay name (profilescope), when the user has one.preferred_usernamestring or nullLogin name (profilescope), when the user has one.emailstring or nullEmail (emailscope), when the user has one.email_verifiedboolean or nullAlwaystruewhenemailis present: Bookclerk trusts the address the Owner recorded.
-
401The access token is missing or invalid. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The token's user is disabled. 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.
$ curl 'http://127.0.0.1:8787/oidc/userinfo' \
-H 'Authorization: Bearer <oidcAccessToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/oidc/userinfo' `
-Headers @{ Authorization = 'Bearer <oidcAccessToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/oidc/userinfo",
headers={"Authorization": "Bearer <oidcAccessToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/oidc/userinfo", {
headers: { Authorization: "Bearer <oidcAccessToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/oidc/userinfo")
.header("Authorization", "Bearer <oidcAccessToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Claims for the token's user.
{
"sub": "7",
"name": "Sam",
"preferred_username": "sam",
"email": "sam@example.com",
"email_verified": true
}
Schema:
{
"type": "object",
"description": "Standard OIDC claims for `GET /oidc/userinfo`, limited to the token's scopes.",
"required": [
"sub"
],
"properties": {
"sub": {
"type": "string",
"description": "Subject: the Bookclerk `users.id` as a string.",
"example": "7"
},
"name": {
"type": [
"string",
"null"
],
"description": "Display name (`profile` scope), when the user has one.",
"example": "Sam"
},
"preferred_username": {
"type": [
"string",
"null"
],
"description": "Login name (`profile` scope), when the user has one.",
"example": "sam"
},
"email": {
"type": [
"string",
"null"
],
"description": "Email (`email` scope), when the user has one.",
"example": "sam@example.com"
},
"email_verified": {
"type": [
"boolean",
"null"
],
"description": "Always `true` when `email` is present: Bookclerk trusts the address the Owner recorded.",
"example": true
}
}
}
Status 401: The access token is missing or invalid.
{
"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 token's 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 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
]
}
}
}
Best-effort refresh-token revoke; always returns 200 per RFC 7009.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
application/x-www-form-urlencoded: RevokeForm
tokenstringrequiredToken to revoke; treated as a refresh token (hashed before lookup).token_type_hintstring or nullOptional hint ignored; this server only stores refresh tokens.
- 200Always 200 (RFC 7009). No body.
$ curl 'http://127.0.0.1:8787/oidc/revoke' \
-X POST \
-d 'token=9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/oidc/revoke' `
-Method Post `
-ContentType 'application/x-www-form-urlencoded' `
-Body 'token=9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d'
import requests
response = requests.post(
"http://127.0.0.1:8787/oidc/revoke",
data={"token": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/oidc/revoke", {
method: "POST",
body: new URLSearchParams("token=9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/oidc/revoke")
.form(&[("token", "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d")])
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Owner/operator list of Bookclerk-as-IdP clients (secrets never included).
Access: The operator, or a signed-in Owner.
Credentials: operatorToken or operatorSession or portalSession
-
200Registered clients (no secrets). Body:
OidcClientsResponse(application/json)1 fieldclientsarray ofOidcClientViewrequiredEvery registered client, without secrets.
-
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.
-
500The clients could not be read (
oidc_client). 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/clients' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/clients' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/auth/oidc/clients",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/clients", {
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/clients")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Registered clients (no secrets).
{
"clients": [
{
"allowed_scopes": [
"openid",
"profile",
"email"
],
"client_id": "audiobookshelf",
"confidential": true,
"enabled": true,
"has_secret": true,
"issue_refresh_token": true,
"name": "Audiobookshelf",
"plugin_id": "audiobookshelf",
"redirect_uris": [
"https://abs.example.com/auth/openid/callback"
]
}
]
}
Schema:
{
"type": "object",
"description": "JSON body for `GET /api/auth/oidc/clients`.",
"required": [
"clients"
],
"properties": {
"clients": {
"type": "array",
"items": {
"type": "object",
"description": "A Bookclerk-as-IdP client as operators see it; the secret appears only when freshly minted.",
"required": [
"client_id",
"redirect_uris",
"confidential",
"issue_refresh_token",
"allowed_scopes",
"has_secret",
"enabled"
],
"properties": {
"client_id": {
"type": "string",
"description": "Public client id used at the authorize and token endpoints.",
"example": "audiobookshelf"
},
"name": {
"type": [
"string",
"null"
],
"description": "Operator-facing display name.",
"example": "Audiobookshelf"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed OAuth redirect URIs.",
"example": [
"https://abs.example.com/auth/openid/callback"
]
},
"confidential": {
"type": "boolean",
"description": "Whether the client authenticates with a secret (otherwise it is a public PKCE client).",
"example": true
},
"issue_refresh_token": {
"type": "boolean",
"description": "Whether token responses include a refresh token.",
"example": true
},
"allowed_scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scopes the client may be granted.",
"example": [
"openid",
"profile",
"email"
]
},
"has_secret": {
"type": "boolean",
"description": "Same as `confidential`: a secret hash is stored.",
"example": true
},
"enabled": {
"type": "boolean",
"description": "Whether the authorize and token endpoints accept this client.",
"example": true
},
"plugin_id": {
"type": [
"string",
"null"
],
"description": "Plugin that provides this client, or `null` for an operator-created one.",
"example": "audiobookshelf"
},
"client_secret": {
"type": [
"string",
"null"
],
"description": "The new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.",
"example": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
}
},
"description": "Every registered client, without secrets."
}
}
}
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 500: The clients could not be read (oidc_client).
{
"error": "oidc_client",
"message": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection",
"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 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.
Create a client; confidential clients return the generated secret once.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: OidcClientWrite
client_idstring or nullPublic client_id (create only; path wins on update).namestring or nullOperator-facing display name.redirect_urisarray of stringAllowed OAuth redirect URIs.confidentialbooleanWhen true, mint a client secret (confidential). When false, public PKCE.issue_refresh_tokenbooleanWhen true, token responses include a refresh token.allowed_scopesarray of stringScopes this client may request (openid,profile,email).enabledbooleanWhen true, authorize and token endpoints accept this client.
-
200The client; a confidential client's secret appears once. Body:
OidcClientView(application/json)10 fieldsclient_idstringrequiredPublic client id used at the authorize and token endpoints.namestring or nullOperator-facing display name.redirect_urisarray of stringrequiredAllowed OAuth redirect URIs.confidentialbooleanrequiredWhether the client authenticates with a secret (otherwise it is a public PKCE client).issue_refresh_tokenbooleanrequiredWhether token responses include a refresh token.allowed_scopesarray of stringrequiredScopes the client may be granted.has_secretbooleanrequiredSame asconfidential: a secret hash is stored.enabledbooleanrequiredWhether the authorize and token endpoints accept this client.plugin_idstring or nullPlugin that provides this client, ornullfor an operator-created one.client_secretstring or nullThe new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.
-
400The client id or a redirect URI is invalid (
oidc_client). 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.
-
409A client with this id already exists (
oidc_client). 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 client could not be read or stored (
oidc_client). 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/clients' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/clients' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/auth/oidc/clients",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/clients", {
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/oidc/clients")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The client; a confidential client's secret appears once.
{
"client_id": "audiobookshelf",
"name": "Audiobookshelf",
"redirect_uris": [
"https://abs.example.com/auth/openid/callback"
],
"confidential": true,
"issue_refresh_token": true,
"allowed_scopes": [
"openid",
"profile",
"email"
],
"has_secret": true,
"enabled": true,
"plugin_id": "audiobookshelf",
"client_secret": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
Schema:
{
"type": "object",
"description": "A Bookclerk-as-IdP client as operators see it; the secret appears only when freshly minted.",
"required": [
"client_id",
"redirect_uris",
"confidential",
"issue_refresh_token",
"allowed_scopes",
"has_secret",
"enabled"
],
"properties": {
"client_id": {
"type": "string",
"description": "Public client id used at the authorize and token endpoints.",
"example": "audiobookshelf"
},
"name": {
"type": [
"string",
"null"
],
"description": "Operator-facing display name.",
"example": "Audiobookshelf"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed OAuth redirect URIs.",
"example": [
"https://abs.example.com/auth/openid/callback"
]
},
"confidential": {
"type": "boolean",
"description": "Whether the client authenticates with a secret (otherwise it is a public PKCE client).",
"example": true
},
"issue_refresh_token": {
"type": "boolean",
"description": "Whether token responses include a refresh token.",
"example": true
},
"allowed_scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scopes the client may be granted.",
"example": [
"openid",
"profile",
"email"
]
},
"has_secret": {
"type": "boolean",
"description": "Same as `confidential`: a secret hash is stored.",
"example": true
},
"enabled": {
"type": "boolean",
"description": "Whether the authorize and token endpoints accept this client.",
"example": true
},
"plugin_id": {
"type": [
"string",
"null"
],
"description": "Plugin that provides this client, or `null` for an operator-created one.",
"example": "audiobookshelf"
},
"client_secret": {
"type": [
"string",
"null"
],
"description": "The new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.",
"example": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
}
}
Status 400: The client id or a redirect URI is invalid (oidc_client). As text/plain, when the body is not syntactically valid JSON.
{
"error": "oidc_client",
"message": "at least one redirect URI is required",
"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 409: A client with this id already exists (oidc_client).
{
"error": "oidc_client",
"message": "a client with this id already exists",
"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: client_id: invalid type: integer `1`, expected a string at line 1 column 14
Schema:
A text/plain body: a string.
Status 500: The client could not be read or stored (oidc_client).
{
"error": "oidc_client",
"message": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection",
"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.
Update redirects, name, scopes, and public/confidential mode; switching a public client to confidential mints its secret, shown once.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
client_idpathstringrequiredClient id.
application/json: OidcClientWrite
client_idstring or nullPublic client_id (create only; path wins on update).namestring or nullOperator-facing display name.redirect_urisarray of stringAllowed OAuth redirect URIs.confidentialbooleanWhen true, mint a client secret (confidential). When false, public PKCE.issue_refresh_tokenbooleanWhen true, token responses include a refresh token.allowed_scopesarray of stringScopes this client may request (openid,profile,email).enabledbooleanWhen true, authorize and token endpoints accept this client.
-
200The client after the change; when the update made a public client confidential, its new secret appears once. Body:
OidcClientView(application/json)10 fieldsclient_idstringrequiredPublic client id used at the authorize and token endpoints.namestring or nullOperator-facing display name.redirect_urisarray of stringrequiredAllowed OAuth redirect URIs.confidentialbooleanrequiredWhether the client authenticates with a secret (otherwise it is a public PKCE client).issue_refresh_tokenbooleanrequiredWhether token responses include a refresh token.allowed_scopesarray of stringrequiredScopes the client may be granted.has_secretbooleanrequiredSame asconfidential: a secret hash is stored.enabledbooleanrequiredWhether the authorize and token endpoints accept this client.plugin_idstring or nullPlugin that provides this client, ornullfor an operator-created one.client_secretstring or nullThe new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.
-
400The client id or a redirect URI is invalid (
oidc_client). 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.
-
404No such client (
oidc_client). 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 client could not be read or stored (
oidc_client). 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/clients/<client_id>' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>", {
method: "PUT",
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
.put("http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The client after the change; when the update made a public client confidential, its new secret appears once.
{
"client_id": "audiobookshelf",
"name": "Audiobookshelf",
"redirect_uris": [
"https://abs.example.com/auth/openid/callback"
],
"confidential": true,
"issue_refresh_token": true,
"allowed_scopes": [
"openid",
"profile",
"email"
],
"has_secret": true,
"enabled": true,
"plugin_id": "audiobookshelf",
"client_secret": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
Schema:
{
"type": "object",
"description": "A Bookclerk-as-IdP client as operators see it; the secret appears only when freshly minted.",
"required": [
"client_id",
"redirect_uris",
"confidential",
"issue_refresh_token",
"allowed_scopes",
"has_secret",
"enabled"
],
"properties": {
"client_id": {
"type": "string",
"description": "Public client id used at the authorize and token endpoints.",
"example": "audiobookshelf"
},
"name": {
"type": [
"string",
"null"
],
"description": "Operator-facing display name.",
"example": "Audiobookshelf"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed OAuth redirect URIs.",
"example": [
"https://abs.example.com/auth/openid/callback"
]
},
"confidential": {
"type": "boolean",
"description": "Whether the client authenticates with a secret (otherwise it is a public PKCE client).",
"example": true
},
"issue_refresh_token": {
"type": "boolean",
"description": "Whether token responses include a refresh token.",
"example": true
},
"allowed_scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scopes the client may be granted.",
"example": [
"openid",
"profile",
"email"
]
},
"has_secret": {
"type": "boolean",
"description": "Same as `confidential`: a secret hash is stored.",
"example": true
},
"enabled": {
"type": "boolean",
"description": "Whether the authorize and token endpoints accept this client.",
"example": true
},
"plugin_id": {
"type": [
"string",
"null"
],
"description": "Plugin that provides this client, or `null` for an operator-created one.",
"example": "audiobookshelf"
},
"client_secret": {
"type": [
"string",
"null"
],
"description": "The new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.",
"example": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
}
}
Status 400: The client id or a redirect URI is invalid (oidc_client). As text/plain, when the body is not syntactically valid JSON.
{
"error": "oidc_client",
"message": "client id may only contain letters, digits, '.', '_', '-', and '~'",
"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 404: No such client (oidc_client).
{
"error": "oidc_client",
"message": "unknown client",
"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 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: client_id: invalid type: integer `1`, expected a string at line 1 column 14
Schema:
A text/plain body: a string.
Status 500: The client could not be read or stored (oidc_client).
{
"error": "oidc_client",
"message": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection",
"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.
Delete a registered client.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
client_idpathstringrequiredClient id.
- 204The client was deleted. 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'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.
-
404No such client (
oidc_client). 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.
-
409The client is provided by a plugin; disable it instead (
oidc_client). 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 client could not be read or removed (
oidc_client). 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/clients/<client_id>' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/clients/<client_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/oidc/clients/<client_id>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 204: The client was deleted. 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'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 404: No such client (oidc_client).
{
"error": "oidc_client",
"message": "unknown client",
"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 409: The client is provided by a plugin; disable it instead (oidc_client).
{
"error": "oidc_client",
"message": "plugin-provided clients cannot be deleted; disable them instead",
"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 500: The client could not be read or removed (oidc_client).
{
"error": "oidc_client",
"message": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection",
"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.
Mint a new secret for a confidential client; plaintext is returned once.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
client_idpathstringrequiredClient id.
-
200The client with its new secret (shown once). Body:
OidcClientView(application/json)10 fieldsclient_idstringrequiredPublic client id used at the authorize and token endpoints.namestring or nullOperator-facing display name.redirect_urisarray of stringrequiredAllowed OAuth redirect URIs.confidentialbooleanrequiredWhether the client authenticates with a secret (otherwise it is a public PKCE client).issue_refresh_tokenbooleanrequiredWhether token responses include a refresh token.allowed_scopesarray of stringrequiredScopes the client may be granted.has_secretbooleanrequiredSame asconfidential: a secret hash is stored.enabledbooleanrequiredWhether the authorize and token endpoints accept this client.plugin_idstring or nullPlugin that provides this client, ornullfor an operator-created one.client_secretstring or nullThe new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.
-
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.
-
404No such client (
oidc_client). 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 secret could not be stored (
oidc_client). 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/clients/<client_id>/rotate-secret' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>/rotate-secret' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>/rotate-secret",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/auth/oidc/clients/<client_id>/rotate-secret", {
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/oidc/clients/<client_id>/rotate-secret")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The client with its new secret (shown once).
{
"client_id": "audiobookshelf",
"name": "Audiobookshelf",
"redirect_uris": [
"https://abs.example.com/auth/openid/callback"
],
"confidential": true,
"issue_refresh_token": true,
"allowed_scopes": [
"openid",
"profile",
"email"
],
"has_secret": true,
"enabled": true,
"plugin_id": "audiobookshelf",
"client_secret": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
Schema:
{
"type": "object",
"description": "A Bookclerk-as-IdP client as operators see it; the secret appears only when freshly minted.",
"required": [
"client_id",
"redirect_uris",
"confidential",
"issue_refresh_token",
"allowed_scopes",
"has_secret",
"enabled"
],
"properties": {
"client_id": {
"type": "string",
"description": "Public client id used at the authorize and token endpoints.",
"example": "audiobookshelf"
},
"name": {
"type": [
"string",
"null"
],
"description": "Operator-facing display name.",
"example": "Audiobookshelf"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed OAuth redirect URIs.",
"example": [
"https://abs.example.com/auth/openid/callback"
]
},
"confidential": {
"type": "boolean",
"description": "Whether the client authenticates with a secret (otherwise it is a public PKCE client).",
"example": true
},
"issue_refresh_token": {
"type": "boolean",
"description": "Whether token responses include a refresh token.",
"example": true
},
"allowed_scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scopes the client may be granted.",
"example": [
"openid",
"profile",
"email"
]
},
"has_secret": {
"type": "boolean",
"description": "Same as `confidential`: a secret hash is stored.",
"example": true
},
"enabled": {
"type": "boolean",
"description": "Whether the authorize and token endpoints accept this client.",
"example": true
},
"plugin_id": {
"type": [
"string",
"null"
],
"description": "Plugin that provides this client, or `null` for an operator-created one.",
"example": "audiobookshelf"
},
"client_secret": {
"type": [
"string",
"null"
],
"description": "The new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.",
"example": "K3mP9qT2vX8bN5cR7wZ1yA4dF6hJ0lS2uE9gI3oV5kM"
}
}
}
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 404: No such client (oidc_client).
{
"error": "oidc_client",
"message": "unknown client",
"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 secret could not be stored (oidc_client).
{
"error": "oidc_client",
"message": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection",
"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.
Generated from crates/bookclerkd/openapi.json at main · View as Markdown