mirror of
https://github.com/logto-io/logto.git
synced 2025-01-06 20:40:08 -05:00
chore(core): add logto-config api doc descriptions (#5033)
* chore(core): add logto-config api doc descriptions * chore(core): polish docs --------- Co-authored-by: Gao Sun <gao@silverhand.io>
This commit is contained in:
Xiao Yijun
GitHub
parent
b1461b42ea
commit
ad60de8f24
2 changed files with 110 additions and 16 deletions
109
packages/core/src/routes/logto-config.openapi.json
Normal file
109
packages/core/src/routes/logto-config.openapi.json
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
{
|
||||
"tags": [
|
||||
{
|
||||
"name": "Configs",
|
||||
"description": "Endpoints for managing Logto global configurations for the tenant."
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/api/configs/admin-console": {
|
||||
"get": {
|
||||
"summary": "Get admin console config",
|
||||
"description": "Get the global configuration object for Logto Console.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "The configuration object."
|
||||
},
|
||||
"404": {
|
||||
"description": "Configuration not found."
|
||||
}
|
||||
}
|
||||
},
|
||||
"patch": {
|
||||
"summary": "Update admin console config",
|
||||
"description": "Update the global configuration object for Logto Console. This method performs a partial update.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "The updated configuration object."
|
||||
},
|
||||
"404": {
|
||||
"description": "Configuration not found."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/configs/oidc/{keyType}": {
|
||||
"get": {
|
||||
"summary": "Get OIDC keys",
|
||||
"description": "Get OIDC keys by key type. The actual key will be redacted from the result.",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "path",
|
||||
"name": "keyType",
|
||||
"description": "Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead."
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "An array of OIDC keys for the given key type."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/configs/oidc/{keyType}/{keyId}": {
|
||||
"delete": {
|
||||
"summary": "Delete OIDC key",
|
||||
"description": "Delete an OIDC key by key type and key ID.",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "path",
|
||||
"name": "keyType",
|
||||
"description": "Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead."
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"204": {
|
||||
"description": "The key was deleted successfully."
|
||||
},
|
||||
"404": {
|
||||
"description": "The key was not found."
|
||||
},
|
||||
"422": {
|
||||
"description": "At least one key must be kept."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/configs/oidc/{keyType}/rotate": {
|
||||
"post": {
|
||||
"summary": "Rotate OIDC keys",
|
||||
"description": "A new key will be generated and prepend to the list of keys.\n\nOnly two recent keys will be kept. The oldest key will be automatically removed if there are more than two keys.",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "path",
|
||||
"name": "keyType",
|
||||
"description": "Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead."
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"properties": {
|
||||
"signingKeyAlgorithm": {
|
||||
"description": "The signing key algorithm the new generated private key is using.\n\nOnly applicable when `keyType` is `private-keys`."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "An array of OIDC keys after rotation."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -90,10 +90,6 @@ export default function logtoConfigRoutes<T extends AuthedRouter>(
|
|||
}
|
||||
);
|
||||
|
||||
/**
|
||||
* Get Logto OIDC private keys from database. The actual key will be redacted from the result.
|
||||
* @param keyType Logto OIDC private key type. Values are either `private-keys` or `cookie-keys`.
|
||||
*/
|
||||
router.get(
|
||||
'/configs/oidc/:keyType',
|
||||
koaGuard({
|
||||
|
|
@ -101,7 +97,7 @@ export default function logtoConfigRoutes<T extends AuthedRouter>(
|
|||
keyType: z.nativeEnum(LogtoOidcConfigKeyType),
|
||||
}),
|
||||
response: z.array(oidcConfigKeysResponseGuard),
|
||||
status: [200, 404],
|
||||
status: [200],
|
||||
}),
|
||||
async (ctx, next) => {
|
||||
const { keyType } = ctx.guard.params;
|
||||
|
|
@ -115,11 +111,6 @@ export default function logtoConfigRoutes<T extends AuthedRouter>(
|
|||
}
|
||||
);
|
||||
|
||||
/**
|
||||
* Delete a Logto OIDC private key from database.
|
||||
* @param keyType Logto OIDC key type. Values are either `oidc.privateKeys` or `oidc.cookieKeys`.
|
||||
* @param keyId The ID of the private key to be deleted.
|
||||
*/
|
||||
router.delete(
|
||||
'/configs/oidc/:keyType/:keyId',
|
||||
koaGuard({
|
||||
|
|
@ -154,12 +145,6 @@ export default function logtoConfigRoutes<T extends AuthedRouter>(
|
|||
}
|
||||
);
|
||||
|
||||
/**
|
||||
* Rotate Logto OIDC private keys. A new key will be generated and added to the list of private keys.
|
||||
* Only keep the last 2 recent keys. The oldest key will be automatically removed if the list exceeds 2 keys.
|
||||
* @param configKey Logto OIDC key type. Values are either `oidc.privateKeys` or `oidc.cookieKeys`.
|
||||
* @param signingKeyAlgorithm The signing key algorithm the new generated private key is using. Values are either `EC` or `RSA`. Only applicable to `oidc.privateKeys`. Defaults to `EC`.
|
||||
*/
|
||||
router.post(
|
||||
'/configs/oidc/:keyType/rotate',
|
||||
koaGuard({
|
||||
|
|
|
|||
Loading…
Reference in a new issue