OIDC provider

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

Last updated View as Markdown

Bookclerk as an OpenID Connect provider for other apps.

Back to the web API reference.

GET /.well-known/openid-configuration

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

Responses

  • 200The OIDC discovery document. Body: DiscoveryDocument (application/json)12 fields
    • issuerstringrequiredIssuer origin used as iss in minted JWTs (public_origin or 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 stringrequiredSupported response_type values; this server only issues code.
    • grant_types_supportedarray of stringrequiredSupported token grants: authorization_code and refresh_token.
    • code_challenge_methods_supportedarray of stringrequiredPKCE methods; only S256 is accepted (plain is rejected).
    • scopes_supportedarray of stringrequiredScopes advertised to clients (openid, profile, and email).
    • 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) or client_secret_post.

Example request

$ 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?);

Example response

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"
      ]
    }
  }
}

GET /oidc/authorize

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

Parameters

  • client_idquerystringrequiredRegistered OIDC client id (must exist in the library store).
  • redirect_uriquerystringrequiredRedirect URI; must match a URI registered for the client.
  • response_typequerystringrequiredOAuth response_type; only code is accepted.
  • scopequerystringSpace-separated scopes; defaults to openid profile when 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 as plain and then rejected.

Responses

  • 303A bookclerk-branch request is sent to the SPA consent page /join/approve, and a bookclerk-clerk request 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 (Accept or Content-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 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403An 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. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The 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. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.

Example request

$ 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?);

Example response

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

POST /oidc/authorize

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

Request body

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_typestringrequiredOAuth response_type; only code is accepted.
  • scopestring or nullSpace-separated scopes; defaults to openid profile when 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 as plain and then rejected.
  • consentstring or nulldeny aborts with access_denied; any other value proceeds to issue a code.

Responses

  • 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 (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in. Browsers get an HTML page; a request that asks for JSON (Accept or Content-Type) gets the standard error body. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 403An 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. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The 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. Body: ErrorJson (application/json); string (text/html)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.

Example request

$ 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?);

Example response

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

POST /oidc/token

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

Request body

application/x-www-form-urlencoded: TokenForm

  • grant_typestringrequiredGrant: authorization_code or refresh_token; anything else is 400.
  • codestring or nullAuthorization code from the redirect (authorization_code grant).
  • 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_token grant).

Responses

  • 200Tokens. Body: TokenResponse (application/json)6 fields
    • access_tokenstringrequiredHS256 JWT access token bound to the User (token_use=access).
    • token_typestringrequiredAlways Bearer for 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 fields
    • errorTokenErrorCoderequiredWhat 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 fields
    • errorTokenErrorCoderequiredWhat 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 fields
    • errorTokenErrorCoderequiredWhat 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.

Example request

$ 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?);

Example response

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."
    }
  }
}

GET /oidc/userinfo

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

Responses

  • 200Claims for the token's user. Body: UserinfoResponse (application/json)5 fields
    • substringrequiredSubject: the Bookclerk users.id as a string.
    • namestring or nullDisplay name (profile scope), when the user has one.
    • preferred_usernamestring or nullLogin name (profile scope), when the user has one.
    • emailstring or nullEmail (email scope), when the user has one.
    • email_verifiedboolean or nullAlways true when email is present: Bookclerk trusts the address the Owner recorded.
  • 401The access token is missing or invalid. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The token's user is disabled. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The user could not be read. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.

Example request

$ 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?);

Example response

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

POST /oidc/revoke

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

Request body

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.

Responses

  • 200Always 200 (RFC 7009). No body.

Example request

$ 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?);

GET /api/auth/oidc/clients

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

Responses

  • 200Registered clients (no secrets). Body: OidcClientsResponse (application/json)1 field
    • clientsarray of OidcClientViewrequiredEvery registered client, without secrets.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller is neither the operator nor an Owner (forbidden), or must enroll a second factor first (mfa_enrollment_required). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The clients could not be read (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/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?);

Example response

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.

POST /api/auth/oidc/clients

Create a client; confidential clients return the generated secret once.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Request body

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.

Responses

  • 200The client; a confidential client's secret appears once. Body: OidcClientView (application/json)10 fields
    • client_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 as confidential: a secret hash is stored.
    • enabledbooleanrequiredWhether the authorize and token endpoints accept this client.
    • plugin_idstring or nullPlugin that provides this client, or null for 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). As text/plain, when the body is not syntactically valid JSON. Body: ErrorJson (application/json); string (text/plain)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409A client with this id already exists (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The client could not be read or stored (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/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?);

Example response

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.

PUT /api/auth/oidc/clients/{client_id}

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

Parameters

  • client_idpathstringrequiredClient id.

Request body

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.

Responses

  • 200The client after the change; when the update made a public client confidential, its new secret appears once. Body: OidcClientView (application/json)10 fields
    • client_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 as confidential: a secret hash is stored.
    • enabledbooleanrequiredWhether the authorize and token endpoints accept this client.
    • plugin_idstring or nullPlugin that provides this client, or null for 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). As text/plain, when the body is not syntactically valid JSON. Body: ErrorJson (application/json); string (text/plain)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such client (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The client could not be read or stored (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/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?);

Example response

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 /api/auth/oidc/clients/{client_id}

Delete a registered client.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • client_idpathstringrequiredClient id.

Responses

  • 204The client was deleted. No body.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such client (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 409The client is provided by a plugin; disable it instead (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The client could not be read or removed (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/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?);

Example response

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.

POST /api/auth/oidc/clients/{client_id}/rotate-secret

Mint a new secret for a confidential client; plaintext is returned once.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • client_idpathstringrequiredClient id.

Responses

  • 200The client with its new secret (shown once). Body: OidcClientView (application/json)10 fields
    • client_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 as confidential: a secret hash is stored.
    • enabledbooleanrequiredWhether the authorize and token endpoints accept this client.
    • plugin_idstring or nullPlugin that provides this client, or null for 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 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such client (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The secret could not be stored (oidc_client). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/auth/oidc/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?);

Example response

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