PPanel Edgeadmin
由 openapi.json 自动生成的 21 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/invitations
GET /api/v1/admin/invitations
Invitations (staff onboarding and invited customers)
{
"parameters": [
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"enum": [
"pending",
"accepted",
"rejected",
"canceled"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvitationList"
}
}
},
"description": "Invitations"
}
},
"summary": "Invitations (staff onboarding and invited customers)",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "iam.staff.manage",
"effectiveSecurity": []
}POST /api/v1/admin/invitations
POST /api/v1/admin/invitations
Invite by email: a staff role within your grant boundary, or customer
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvitationCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invitation"
}
}
},
"description": "Invited"
}
},
"summary": "Invite by email: a staff role within your grant boundary, or customer",
"tags": [
"admin"
],
"x-audit": "iam.invitation.create",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "iam.staff.manage",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/invitations/{id}/cancel
POST /api/v1/admin/invitations/{id}/cancel
Cancel a pending invitation
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invitation"
}
}
},
"description": "Canceled"
}
},
"summary": "Cancel a pending invitation",
"tags": [
"admin"
],
"x-audit": "iam.invitation.cancel",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "iam.staff.manage",
"effectiveSecurity": []
}GET /api/v1/admin/me
GET /api/v1/admin/me
Signed-in staff member: roles, permission codes, MFA state, permissions ETag (open before MFA)
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminMe"
}
}
},
"description": "Staff session"
}
},
"summary": "Signed-in staff member: roles, permission codes, MFA state, permissions ETag (open before MFA)",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}GET /api/v1/admin/permissions
GET /api/v1/admin/permissions
The permission and capability catalogue
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionCatalogue"
}
}
},
"description": "Catalogue"
}
},
"summary": "The permission and capability catalogue",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "iam.role.manage",
"effectiveSecurity": []
}GET /api/v1/admin/roles
GET /api/v1/admin/roles
Roles with their permission codes and whether the caller may assign them
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleList"
}
}
},
"description": "Roles"
}
},
"summary": "Roles with their permission codes and whether the caller may assign them",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": [
"iam.role.manage",
"iam.staff.manage"
],
"effectiveSecurity": []
}POST /api/v1/admin/roles
POST /api/v1/admin/roles
Create a role from catalogue codes within your own permissions
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Role"
}
}
},
"description": "Created",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Create a role from catalogue codes within your own permissions",
"tags": [
"admin"
],
"x-audit": "iam.role.create",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true
},
"x-idempotency": "required",
"x-permission": "iam.role.manage",
"x-reauth": true,
"effectiveSecurity": []
}DELETE /api/v1/admin/roles/{role}
DELETE /api/v1/admin/roles/{role}
Delete a role (removed from every member); customer cannot be deleted
{
"parameters": [
{
"in": "path",
"name": "role",
"required": true,
"schema": {
"pattern": "^[a-z][a-z0-9_]{1,31}$",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
}
},
"summary": "Delete a role (removed from every member); customer cannot be deleted",
"tags": [
"admin"
],
"x-audit": "iam.role.delete",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "iam.role.manage",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/roles/{role}
GET /api/v1/admin/roles/{role}
One role (ETag for If-Match)
{
"parameters": [
{
"in": "path",
"name": "role",
"required": true,
"schema": {
"pattern": "^[a-z][a-z0-9_]{1,31}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Role"
}
}
},
"description": "Role",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "One role (ETag for If-Match)",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "iam.role.manage",
"effectiveSecurity": []
}PUT /api/v1/admin/roles/{role}
PUT /api/v1/admin/roles/{role}
Replace a role’s permission codes (If-Match)
{
"parameters": [
{
"in": "path",
"name": "role",
"required": true,
"schema": {
"pattern": "^[a-z][a-z0-9_]{1,31}$",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Role"
}
}
},
"description": "Updated",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Replace a role’s permission codes (If-Match)",
"tags": [
"admin"
],
"x-audit": "iam.role.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "none",
"x-permission": "iam.role.manage",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/settings/captcha/test
POST /api/v1/admin/settings/captcha/test
Check the saved configuration of one human-verification provider
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CaptchaProviderTestRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CaptchaProviderTestResult"
}
}
},
"description": "Result"
}
},
"summary": "Check the saved configuration of one human-verification provider",
"tags": [
"admin"
],
"x-audit": "iam.captcha.test",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "none",
"x-permission": "iam.auth_provider.manage",
"effectiveSecurity": []
}GET /api/v1/admin/staff
GET /api/v1/admin/staff
Staff members
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StaffList"
}
}
},
"description": "Staff"
}
},
"summary": "Staff members",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "iam.staff.manage",
"effectiveSecurity": []
}GET /api/v1/admin/staff/{userId}
GET /api/v1/admin/staff/{userId}
Staff member with assignable roles
{
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StaffDetail"
}
}
},
"description": "Staff member",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Staff member with assignable roles",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "iam.staff.manage",
"effectiveSecurity": []
}POST /api/v1/admin/staff/{userId}/reset-mfa
POST /api/v1/admin/staff/{userId}/reset-mfa
Remove the TOTP enrollment and every session of a staff account
{
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StaffMfaReset"
}
}
},
"description": "Reset"
}
},
"summary": "Remove the TOTP enrollment and every session of a staff account",
"tags": [
"admin"
],
"x-audit": "iam.staff.mfa.reset",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "iam.staff.manage",
"x-reauth": true,
"effectiveSecurity": []
}PUT /api/v1/admin/staff/{userId}/roles
PUT /api/v1/admin/staff/{userId}/roles
Set a member’s roles (customer is kept; empty list demotes to customer). If-Match.
{
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StaffRolesUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StaffRoles"
}
}
},
"description": "Roles",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Set a member’s roles (customer is kept; empty list demotes to customer). If-Match.",
"tags": [
"admin"
],
"x-audit": "iam.staff.roles.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "none",
"x-permission": "iam.staff.manage",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/users
GET /api/v1/admin/users
Search and list accounts (masked; keyset pagination)
{
"parameters": [
{
"description": "Email (exact, or prefix), phone, user id, public id, subscription id, node credential UUID or node id, or the lowercase hex SHA-256 fingerprint (≥ 12 digits, prefix) of a subscription-link token or node credential — hash secrets client-side, never send them",
"in": "query",
"name": "q",
"required": false,
"schema": {
"description": "Email (exact, or prefix), phone, user id, public id, subscription id, node credential UUID or node id, or the lowercase hex SHA-256 fingerprint (≥ 12 digits, prefix) of a subscription-link token or node credential — hash secrets client-side, never send them",
"maxLength": 64,
"type": "string"
}
},
{
"description": "Account status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"active",
"disabled",
"banned",
"deactivating",
"deleted"
],
"type": "string"
},
{
"items": {
"enum": [
"active",
"disabled",
"banned",
"deactivating",
"deleted"
],
"type": "string"
},
"maxItems": 20,
"type": "array"
}
],
"description": "Account status; repeat the parameter for several values"
}
},
{
"description": "Holds this staff role (not customer: use staff=false); repeat the parameter for several values",
"in": "query",
"name": "role",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"maxItems": 20,
"type": "array"
}
],
"description": "Holds this staff role (not customer: use staff=false); repeat the parameter for several values"
}
},
{
"description": "true: holds a role other than customer; false: customers only",
"in": "query",
"name": "staff",
"required": false,
"schema": {
"description": "true: holds a role other than customer; false: customers only",
"enum": [
"true",
"false"
],
"type": "string"
}
},
{
"description": "Referrer user id",
"in": "query",
"name": "invited_by",
"required": false,
"schema": {
"description": "Referrer user id",
"format": "uuid",
"type": "string"
}
},
{
"description": "Registered at or after",
"in": "query",
"name": "created_from",
"required": false,
"schema": {
"description": "Registered at or after",
"format": "date-time",
"type": "string"
}
},
{
"description": "Registered before",
"in": "query",
"name": "created_to",
"required": false,
"schema": {
"description": "Registered before",
"format": "date-time",
"type": "string"
}
},
{
"description": "Holds an active or exhausted subscription ending at or after",
"in": "query",
"name": "subscription_ends_from",
"required": false,
"schema": {
"description": "Holds an active or exhausted subscription ending at or after",
"format": "date-time",
"type": "string"
}
},
{
"description": "… ending before",
"in": "query",
"name": "subscription_ends_to",
"required": false,
"schema": {
"description": "… ending before",
"format": "date-time",
"type": "string"
}
},
{
"description": "Default created_at (desc); email (asc)",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"description": "Default created_at (desc); email (asc)",
"enum": [
"created_at",
"email"
],
"type": "string"
}
},
{
"in": "query",
"name": "order",
"required": false,
"schema": {
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 2048,
"minLength": 1,
"type": "string"
}
},
{
"description": "Jump to page (admin only; not with cursor; offset ≤ 10,000)",
"in": "query",
"name": "page",
"required": false,
"schema": {
"description": "Jump to page (admin only; not with cursor; offset ≤ 10,000)",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserPage"
}
}
},
"description": "A page of accounts"
}
},
"summary": "Search and list accounts (masked; keyset pagination)",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "iam.user.read",
"effectiveSecurity": []
}GET /api/v1/admin/users/{id}
GET /api/v1/admin/users/{id}
Account detail with roles (masked; ETag = user version)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserDetail"
}
}
},
"description": "Account",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Account detail with roles (masked; ETag = user version)",
"tags": [
"admin"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "iam.user.read",
"effectiveSecurity": []
}PATCH /api/v1/admin/users/{id}
PATCH /api/v1/admin/users/{id}
Edit name, language, time zone or email using If-Match. For staff targets, the caller must hold every target permission and cannot target itself.
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserDetail"
}
}
},
"description": "Updated account",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Edit name, language, time zone or email using If-Match. For staff targets, the caller must hold every target permission and cannot target itself.",
"tags": [
"admin"
],
"x-audit": "iam.user.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "none",
"x-permission": "iam.user.update",
"effectiveSecurity": []
}GET /api/v1/admin/users/{id}/sensitive
GET /api/v1/admin/users/{id}/sensitive
Full email and phone (re-authentication; audited)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminUserSensitive"
}
}
},
"description": "Contact data"
}
},
"summary": "Full email and phone (re-authentication; audited)",
"tags": [
"admin"
],
"x-audit": "iam.user.sensitive.read",
"x-body": "none",
"x-body-limit": 0,
"x-permission": "iam.user.read_sensitive",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/users/{id}/sessions/revoke
POST /api/v1/admin/users/{id}/sessions/revoke
Revoke every session of an account
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionsRevoked"
}
}
},
"description": "Revoked"
}
},
"summary": "Revoke every session of an account",
"tags": [
"admin"
],
"x-audit": "iam.user.sessions.revoke",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "iam.user.session_revoke",
"effectiveSecurity": []
}POST /api/v1/admin/users/{id}/status
POST /api/v1/admin/users/{id}/status
Enable, disable or ban an account (deletes its sessions; If-Match = user version)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserStatusChange"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserStatus"
}
}
},
"description": "Status",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Enable, disable or ban an account (deletes its sessions; If-Match = user version)",
"tags": [
"admin"
],
"x-audit": "iam.user.status",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "none",
"x-permission": "iam.user.status",
"effectiveSecurity": []
}