{
  "openapi": "3.1.0",
  "info": {
    "title": "NexusMC 开放平台 API",
    "version": "1.0.0",
    "description": "开放平台 OAuth confidential client 协议。"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:4520"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauthBearer": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "http://127.0.0.1:4520/v1/oauth2/authorize",
            "tokenUrl": "http://127.0.0.1:4520/v1/oauth2/token",
            "scopes": {
              "profile:read": "读取公开个人资料",
              "email:read": "读取邮箱与验证状态",
              "resource:read:feed": "读取资源",
              "resource:read:self": "读取本人的资源",
              "resource:create": "创建资源",
              "resource:update:self": "修改本人维护的资源",
              "resource:delete:self": "删除本人维护的资源",
              "post:read:feed": "读取帖子",
              "post:read:self": "读取本人的帖子",
              "post:create": "发布帖子与回复",
              "post:update:self": "修改本人的帖子",
              "post:delete:self": "删除本人的帖子",
              "user:read:self": "读取本人的展示资料",
              "organization:read:self": "读取本人可见的组织",
              "organization:create": "创建组织",
              "organization:update:self": "修改本人拥有的组织",
              "bot:dm:read": "接收用户私信",
              "bot:dm:reply": "回复用户私信",
              "bot:room:mention": "接收房间提及指令",
              "bot:room:slash": "接收房间无提及指令",
              "bot:room:reply": "回复房间指令",
              "bot:events:read": "接收机器人事件"
            }
          }
        }
      },
      "clientBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "Confidential client。也可在 body 中传 client_id/client_secret。"
      }
    },
    "schemas": {},
    "parameters": {}
  },
  "paths": {
    "/v1/oauth2/scopes": {
      "get": {
        "operationId": "listOAuthScopes",
        "tags": [
          "OAuth"
        ],
        "summary": "列出可申请的 OAuth scope",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {
                  "scopes": [
                    {
                      "value": "profile:read",
                      "label": "读取基本资料"
                    }
                  ]
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "enum": [
                              "profile:read",
                              "email:read",
                              "resource:read:feed",
                              "resource:read:self",
                              "resource:create",
                              "resource:update:self",
                              "resource:delete:self",
                              "post:read:feed",
                              "post:read:self",
                              "post:create",
                              "post:update:self",
                              "post:delete:self",
                              "user:read:self",
                              "organization:read:self",
                              "organization:create",
                              "organization:update:self",
                              "bot:dm:read",
                              "bot:dm:reply",
                              "bot:room:mention",
                              "bot:room:slash",
                              "bot:room:reply",
                              "bot:events:read"
                            ]
                          },
                          "label": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "value",
                          "label"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "scopes"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "SERVICE_UNAVAILABLE",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-cookie-policy": "reject",
        "x-legacy-api-path": "/api/oauth2/scopes"
      }
    },
    "/v1/oauth2/authorize": {
      "get": {
        "operationId": "authorizeOAuth",
        "tags": [
          "OAuth"
        ],
        "summary": "发起授权码流程",
        "description": "Confidential client；仅接受 response_type=code 和 S256 PKCE。成功时 302 重定向至本站授权页，失败返回 OAuth {error}。",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "code"
              ]
            },
            "required": true,
            "name": "response_type",
            "in": "query",
            "example": "code"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": true,
            "name": "client_id",
            "in": "query",
            "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
          },
          {
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "required": true,
            "name": "redirect_uri",
            "in": "query",
            "example": "https://example.com/oauth/callback"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": true,
            "name": "scope",
            "in": "query",
            "example": "profile:read"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 1024
            },
            "required": false,
            "name": "state",
            "in": "query",
            "example": "REPLACE_WITH_RANDOM_STATE"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{43}$"
            },
            "required": true,
            "name": "code_challenge",
            "in": "query",
            "example": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "S256"
              ]
            },
            "required": true,
            "name": "code_challenge_method",
            "in": "query",
            "example": "S256"
          }
        ],
        "responses": {
          "302": {
            "description": "重定向到本站授权页",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "400": {
            "description": "OAuth 协议错误",
            "content": {
              "application/json": {
                "example": {
                  "error": "invalid_request"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_request",
                        "invalid_client",
                        "invalid_grant",
                        "invalid_scope",
                        "unsupported_grant_type",
                        "unsupported_response_type",
                        "access_denied",
                        "server_error"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "x-cookie-policy": "authorize-session-only",
        "x-legacy-api-path": "/api/oauth2/authorize"
      }
    },
    "/v1/oauth2/token": {
      "post": {
        "operationId": "exchangeOAuthToken",
        "tags": [
          "OAuth"
        ],
        "summary": "交换、刷新令牌或签发机器人令牌",
        "description": "Confidential client 使用 HTTP Basic 或请求体 client_id/client_secret，二者不可同时使用；不接受 Cookie。body 支持 form-urlencoded 或全字符串 JSON，最大 16KiB，重复字段拒绝。授权码交换必须提交 S256 code_verifier；刷新令牌轮换，重放撤销整族。 绑定机器人的审核应用可使用 client_credentials 申请短期机器人 access token；该 grant 不签发 refresh token。",
        "security": [
          {
            "clientBasic": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "client_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "client_secret": "REPLACE_WITH_CLIENT_SECRET",
                "grant_type": "authorization_code",
                "code": "REPLACE_WITH_CALLBACK_CODE",
                "redirect_uri": "https://example.com/oauth/callback",
                "code_verifier": "REPLACE_WITH_RANDOM_VERIFIER_AT_LEAST_43_CHARS"
              },
              "schema": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "client_id": {
                        "type": "string"
                      },
                      "client_secret": {
                        "type": "string"
                      },
                      "grant_type": {
                        "type": "string",
                        "enum": [
                          "authorization_code"
                        ]
                      },
                      "code": {
                        "type": "string"
                      },
                      "redirect_uri": {
                        "type": "string",
                        "format": "uri"
                      },
                      "code_verifier": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9._~-]{43,128}$"
                      }
                    },
                    "required": [
                      "grant_type",
                      "code",
                      "redirect_uri",
                      "code_verifier"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "client_id": {
                        "type": "string"
                      },
                      "client_secret": {
                        "type": "string"
                      },
                      "grant_type": {
                        "type": "string",
                        "enum": [
                          "refresh_token"
                        ]
                      },
                      "refresh_token": {
                        "type": "string"
                      },
                      "scope": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "grant_type",
                      "refresh_token"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "client_id": {
                        "type": "string"
                      },
                      "client_secret": {
                        "type": "string"
                      },
                      "grant_type": {
                        "type": "string",
                        "enum": [
                          "client_credentials"
                        ]
                      },
                      "scope": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "grant_type"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            },
            "application/x-www-form-urlencoded": {
              "example": {
                "client_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "client_secret": "REPLACE_WITH_CLIENT_SECRET",
                "grant_type": "authorization_code",
                "code": "REPLACE_WITH_CALLBACK_CODE",
                "redirect_uri": "https://example.com/oauth/callback",
                "code_verifier": "REPLACE_WITH_RANDOM_VERIFIER_AT_LEAST_43_CHARS"
              },
              "schema": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "client_id": {
                        "type": "string"
                      },
                      "client_secret": {
                        "type": "string"
                      },
                      "grant_type": {
                        "type": "string",
                        "enum": [
                          "authorization_code"
                        ]
                      },
                      "code": {
                        "type": "string"
                      },
                      "redirect_uri": {
                        "type": "string",
                        "format": "uri"
                      },
                      "code_verifier": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9._~-]{43,128}$"
                      }
                    },
                    "required": [
                      "grant_type",
                      "code",
                      "redirect_uri",
                      "code_verifier"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "client_id": {
                        "type": "string"
                      },
                      "client_secret": {
                        "type": "string"
                      },
                      "grant_type": {
                        "type": "string",
                        "enum": [
                          "refresh_token"
                        ]
                      },
                      "refresh_token": {
                        "type": "string"
                      },
                      "scope": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "grant_type",
                      "refresh_token"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "client_id": {
                        "type": "string"
                      },
                      "client_secret": {
                        "type": "string"
                      },
                      "grant_type": {
                        "type": "string",
                        "enum": [
                          "client_credentials"
                        ]
                      },
                      "scope": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "grant_type"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {
                  "access_token": "REPLACE_WITH_ACCESS_TOKEN",
                  "token_type": "Bearer",
                  "expires_in": 3600,
                  "refresh_token": "REPLACE_WITH_REFRESH_TOKEN",
                  "scope": "profile:read"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string",
                      "enum": [
                        "Bearer"
                      ]
                    },
                    "expires_in": {
                      "type": "integer"
                    },
                    "refresh_token": {
                      "type": "string"
                    },
                    "scope": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "access_token",
                    "token_type",
                    "expires_in",
                    "scope"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "OAuth 协议错误",
            "content": {
              "application/json": {
                "example": {
                  "error": "invalid_request"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_request",
                        "invalid_client",
                        "invalid_grant",
                        "invalid_scope",
                        "unsupported_grant_type",
                        "unsupported_response_type",
                        "access_denied",
                        "server_error"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "OAuth 协议错误",
            "content": {
              "application/json": {
                "example": {
                  "error": "invalid_client"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_request",
                        "invalid_client",
                        "invalid_grant",
                        "invalid_scope",
                        "unsupported_grant_type",
                        "unsupported_response_type",
                        "access_denied",
                        "server_error"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "x-cookie-policy": "reject",
        "x-legacy-api-path": "/api/oauth2/token"
      }
    },
    "/v1/oauth2/revoke": {
      "post": {
        "operationId": "revokeOAuthToken",
        "tags": [
          "OAuth"
        ],
        "summary": "撤销访问或刷新令牌",
        "description": "Confidential client 使用 Basic 或 body 凭据；未知令牌也返回空对象。",
        "security": [
          {
            "clientBasic": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "client_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "client_secret": "REPLACE_WITH_CLIENT_SECRET",
                "token": "REPLACE_WITH_ACCESS_OR_REFRESH_TOKEN",
                "token_type_hint": "refresh_token"
              },
              "schema": {
                "type": "object",
                "properties": {
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "token": {
                    "type": "string"
                  },
                  "token_type_hint": {
                    "type": "string",
                    "enum": [
                      "access_token",
                      "refresh_token"
                    ]
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": false
              }
            },
            "application/x-www-form-urlencoded": {
              "example": {
                "client_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "client_secret": "REPLACE_WITH_CLIENT_SECRET",
                "token": "REPLACE_WITH_ACCESS_OR_REFRESH_TOKEN",
                "token_type_hint": "refresh_token"
              },
              "schema": {
                "type": "object",
                "properties": {
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "token": {
                    "type": "string"
                  },
                  "token_type_hint": {
                    "type": "string",
                    "enum": [
                      "access_token",
                      "refresh_token"
                    ]
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {},
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "OAuth 协议错误",
            "content": {
              "application/json": {
                "example": {
                  "error": "invalid_request"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_request",
                        "invalid_client",
                        "invalid_grant",
                        "invalid_scope",
                        "unsupported_grant_type",
                        "unsupported_response_type",
                        "access_denied",
                        "server_error"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "OAuth 协议错误",
            "content": {
              "application/json": {
                "example": {
                  "error": "invalid_client"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_request",
                        "invalid_client",
                        "invalid_grant",
                        "invalid_scope",
                        "unsupported_grant_type",
                        "unsupported_response_type",
                        "access_denied",
                        "server_error"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "x-cookie-policy": "reject",
        "x-legacy-api-path": "/api/oauth2/revoke"
      }
    },
    "/v1/oauth2/userinfo": {
      "get": {
        "operationId": "getOAuthUserinfo",
        "tags": [
          "OAuth"
        ],
        "summary": "读取授权用户信息",
        "description": "仅接受 OAuth access token；sub 始终返回，profile:read 与 email:read 各控制对应字段。",
        "security": [
          {
            "oauthBearer": [
              "profile:read"
            ]
          },
          {
            "oauthBearer": [
              "email:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {
                  "sub": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                  "preferred_username": "example-user",
                  "name": "示例用户"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "sub": {
                      "type": "string"
                    },
                    "preferred_username": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "picture": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "x-platform-site-url": true
                    },
                    "email": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "email_verified": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "sub"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求错误",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-cookie-policy": "reject",
        "x-legacy-api-path": "/api/oauth2/userinfo"
      }
    }
  },
  "webhooks": {}
}
