{ "openapi": "3.1.0", "info": { "title": "OceanWay Core token management slice", "version": "0.1.0-draft" }, "x-source-commit": "385d2dfd10d821b25c8a6766bd16eea248cb1652", "x-status": "local_identity_configured", "security": [ { "Access": [] } ], "paths": { "/api/token/": { "post": { "operationId": "AddToken", "responses": { "200": { "description": "Inspect success; business/validation/persistence errors retain upstream HTTP 200. All responses no-store.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NoDataSuccess" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "403": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "500": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } } }, "requestBody": { "required": true, "description": "JSON object, maximum encoded body 65536 bytes. Unknown fields ignored; protected fields never written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInput" } } } }, "x-authorization": "Live browser session is rechecked within the user/session/token transaction. Audit commits with the write; failure rolls back. Allowed Origin/Referer required." }, "put": { "operationId": "UpdateToken", "responses": { "200": { "description": "Inspect success; business/validation/persistence errors retain upstream HTTP 200. All responses no-store.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DetailSuccess" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "403": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "500": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } } }, "requestBody": { "required": true, "description": "JSON object, maximum encoded body 65536 bytes. Unknown fields ignored; protected fields never written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInput" } } } }, "parameters": [ { "in": "query", "name": "status_only", "schema": { "type": "string" }, "description": "Any nonempty string, including false or 0, selects status-only update. Empty or absent means replacement of editable fields, not PATCH." } ], "x-authorization": "Live browser session is rechecked within the user/session/token transaction. Audit commits with the write; failure rolls back. Allowed Origin/Referer required." } }, "/api/token/{id}": { "delete": { "operationId": "DeleteToken", "responses": { "200": { "description": "Inspect success; business/validation/persistence errors retain upstream HTTP 200. All responses no-store.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NoDataSuccess" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "403": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "500": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-authorization": "Live browser session is rechecked within the user/session/token transaction. Audit commits with the write; failure rolls back. Allowed Origin/Referer required." } }, "/api/token/search": { "get": { "operationId": "SearchTokens", "responses": { "200": { "description": "Inspect success; business/validation/persistence errors retain upstream HTTP 200. All responses no-store.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ListSuccess" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "403": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "500": { "description": "Authentication, Origin, rate or internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } } }, "parameters": [ { "name": "p", "in": "query", "schema": { "type": "integer" }, "description": "Page; missing, malformed or nonpositive becomes 1." }, { "name": "page_size", "in": "query", "schema": { "type": "integer" }, "description": "Preferred size; zero or malformed falls back to ps then size. Negative becomes 10. Above 100 caps at 100." }, { "name": "ps", "in": "query", "schema": { "type": "integer" }, "description": "Legacy size alias." }, { "name": "size", "in": "query", "schema": { "type": "integer" }, "description": "Legacy token page size alias. Final default 10." }, { "in": "query", "name": "keyword", "schema": { "type": "string" }, "description": "Name filter; at most 256 bytes. Exact LIKE unless explicit % is used; _ and ! escaped." }, { "in": "query", "name": "token", "schema": { "type": "string" }, "description": "Key filter; optional sk- prefix stripped. Same pattern rules; results always masked." } ], "x-pattern": "Reject %% or more than two %; wildcard keyword needs at least two bytes after escaping/removing %. Owner-scoped count and pagination; oversized accounts cannot use fuzzy search. Case behavior follows database LIKE collation." } } }, "components": { "schemas": { "MaskedToken": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "integer" }, "created_time": { "type": "integer" }, "accessed_time": { "type": "integer" }, "expired_time": { "type": "integer" }, "remain_quota": { "type": "integer" }, "used_quota": { "type": "integer" }, "key": { "type": "string", "description": "Masked in list/detail. Full value only in explicit key retrieval response." }, "name": { "type": "string" }, "model_limits": { "type": "string" }, "group": { "type": "string" }, "unlimited_quota": { "type": "boolean" }, "model_limits_enabled": { "type": "boolean" }, "cross_group_retry": { "type": "boolean" }, "allow_ips": { "type": [ "string", "null" ] }, "DeletedAt": { "type": [ "string", "null" ], "description": "Upstream GORM field casing retained; active rows return null." }, "auto_groups": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "user_id", "status", "created_time", "accessed_time", "expired_time", "remain_quota", "used_quota", "key", "name", "model_limits", "group", "unlimited_quota", "model_limits_enabled", "cross_group_retry", "allow_ips", "DeletedAt", "auto_groups" ], "additionalProperties": false }, "Page": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MaskedToken" } } }, "required": [ "page", "page_size", "total", "items" ], "additionalProperties": false }, "FullKey": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "success": { "const": false }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false }, "ListSuccess": { "type": "object", "properties": { "success": { "const": true }, "message": { "const": "" }, "data": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "message", "data" ], "additionalProperties": false }, "DetailSuccess": { "type": "object", "properties": { "success": { "const": true }, "message": { "const": "" }, "data": { "$ref": "#/components/schemas/MaskedToken" } }, "required": [ "success", "message", "data" ], "additionalProperties": false }, "KeySuccess": { "type": "object", "properties": { "success": { "const": true }, "message": { "const": "" }, "data": { "$ref": "#/components/schemas/FullKey" } }, "required": [ "success", "message", "data" ], "additionalProperties": false }, "AuthError": { "type": "object", "properties": { "success": { "const": false }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "success", "code", "message" ], "additionalProperties": false }, "NoDataSuccess": { "type": "object", "properties": { "success": { "const": true }, "message": { "const": "" } }, "required": [ "success", "message" ], "additionalProperties": false }, "TokenInput": { "type": "object", "properties": { "id": { "type": "integer", "description": "Ignored on create; required positive target ID on update." }, "user_id": { "type": "integer", "description": "Accepted in legacy-shaped payloads but ignored; server owned." }, "status": { "type": "integer", "description": "Ignored on create and ordinary update. For status_only only 1 (enable) or 2 (disable) accepted." }, "created_time": { "type": "integer", "description": "Accepted in legacy-shaped payloads but ignored; server owned." }, "accessed_time": { "type": "integer", "description": "Accepted in legacy-shaped payloads but ignored; server owned." }, "expired_time": { "type": "integer", "minimum": -1, "description": "Unix seconds; -1 means no expiry. Create zero/omitted becomes -1 by upstream GORM default; ordinary update zero remains zero." }, "remain_quota": { "type": "integer", "minimum": 0, "maximum": 500000000000000, "description": "Key budget bound from fixed upstream; never a wallet credit or RMB conversion." }, "used_quota": { "type": "integer", "description": "Accepted in legacy-shaped payloads but ignored; server owned." }, "key": { "type": "string", "description": "Accepted in legacy-shaped payloads but ignored; server owned." }, "name": { "type": "string", "description": "At most 50 UTF-8 bytes. Empty is allowed." }, "model_limits": { "type": "string", "description": "At most 16384 bytes; must be nonempty if enabled. Enforcement is part of the pending invocation path." }, "group": { "type": "string", "description": "Empty inherits account group; otherwise must equal current account group. auto and other groups unavailable in this slice." }, "unlimited_quota": { "type": "boolean" }, "model_limits_enabled": { "type": "boolean" }, "cross_group_retry": { "type": "boolean", "description": "Normalized to false; automatic groups not supported." }, "allow_ips": { "type": [ "string", "null" ], "description": "At most 4096 bytes; newline-separated IP addresses or CIDRs, nullable. Invocation enforcement pending." }, "DeletedAt": { "type": [ "string", "null" ], "description": "Accepted in legacy-shaped payloads but ignored; server owned." }, "auto_groups": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Ignored and cleared for non-auto groups. auto itself is rejected." } }, "required": [], "additionalProperties": true }, "UpdateInput": { "allOf": [ { "$ref": "#/components/schemas/TokenInput" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "minimum": 1 } } } ] } }, "securitySchemes": { "Access": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }