{ "openapi": "3.0.0", "info": { "version": "0.7.1", "title": "splinterd API", "description": "REST API for the Splinter daemon" }, "servers": [ { "url": "http://localhost:9000/api" } ], "paths": { "/status": { "get": { "tags": [ "Diagnostics" ], "description": "Used to check if server is successfully running\n\nThis endpoint requires the permission \"status.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "Server is running correctly and accepting connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/proposals": { "get": { "summary": "Fetches a list of pending circuit proposals for this node", "description": "This endpoint can be used to view all of the circuit proposals that the\nnode is a proposed member of. If a circuit management type is provided\nvia the \"management_type\" query parameter, only circuit proposals that\nhave the given circuit management type will be returned. If a node ID is\nprovided via the \"member\" query parameter, only circuit proposals that\nhave the given node as a member will be returned. If no filter is\nprovided, all of the node's circuit proposals will be returned.\n\nThis endpoint requires the permission \"circuit.read\".\n", "tags": [ "Proposals" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "offset", "in": "query", "description": "paging offset", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "maximum number of items to return (max 100)", "required": false, "schema": { "type": "integer", "default": 100 } }, { "name": "management_type", "in": "query", "description": "Only show proposed circuits matching the given circuit management\ntype", "required": false, "schema": { "type": "string" } }, { "name": "member", "in": "query", "description": "Only show proposed circuits that have a member with the given node\nID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of proposals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/proposals/{circuit_id}": { "get": { "summary": "Fetches a circuit proposal by the circuit's ID", "description": "This endpoint can be used to view a specific circuit proposal that the\nnode is a proposed member of.\n\nThis endpoint requires the permission \"circuit.read\".\n", "tags": [ "Proposals" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "circuit_id", "in": "path", "description": "Circuit ID of the proposal to fetch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the requested proposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proposal" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The requested circuit proposal was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/submit": { "post": { "tags": [ "Admin Service" ], "description": "Send circuit management payload in bytes to admin service\n\nThis endpoint requires the permission \"circuit.write\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "202": { "description": "The circuit management payload was accepted" }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ws/admin/register/{type}": { "get": { "tags": [ "Admin Service" ], "description": "Register the handler for a circuit management type\n\nThis endpoint requires the permission \"circuit.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "type", "description": "The circuit management type is the type of circuit the handler will manage", "in": "path", "required": true, "schema": { "type": "string" }, "x-example": "gameroom" }, { "name": "last", "description": "A timestamp in milliseconds from the Unix Epoch, indicating the last received event.", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Registration request was successfully submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationRegistration" } } } }, "400": { "description": "The circuit management type was invalid or the request was malformed\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/circuits": { "get": { "summary": "Fetches a list of circuits that the node belongs to", "description": "This endpoint can be used to view all or some of the circuits that the\nnode is a member of. If a node ID is provided via the \"filter\" query\nparameter, only circuits that have the given node ID as a member will be\nreturned. If a circuit status is provided via the \"status\" query\nparameter, only circuits that have the given circuit status will be\nreturned; if no filter is provided, all of the node's `Active` circuits\nwill be returned.\n\nThis endpoint requires the permission \"circuit.read\".\n", "tags": [ "Circuits" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "offset", "in": "query", "description": "paging offset", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "maximum number of items to return (max 100)", "required": false, "schema": { "type": "integer", "default": 100 } }, { "name": "filter", "in": "query", "description": "Node ID that must be present in the returned circuits", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Circuit status of the returned circuits", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of circuits", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Circuit" } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/circuits/{circuit_id}": { "get": { "summary": "Fetches a circuit by its ID", "description": "This endpoint can be used to view a specific circuit that the node is a\nmember of.\n\nThis endpoint requires the permission \"circuit.read\".\n", "tags": [ "Circuits" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "circuit_id", "in": "path", "description": "ID of the circuit to fetch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the requested circuit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Circuit" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The requested circuit was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/authorization/assignments": { "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "get": { "tags": [ "Authorization" ], "summary": "Get all assignments", "description": "Gets all assignments.\n\nThis endpoint requires the permission \"authorization.rbac.read\".\n", "parameters": [ { "$ref": "#/components/parameters/paging" } ], "responses": { "200": { "description": "Get list of all assignments", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/Assignment" } } } } }, "400": { "description": "Malformed query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "400", "message": "Malformed Query" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "500", "message": "Internal Server Error" } } } } } }, "post": { "tags": [ "Authorization" ], "summary": "Add a new assignment", "description": "Adds a new assignment\nThis endpoint requires the permission \"authorization.rbac.write\".", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentPayload" } } } }, "responses": { "200": { "description": "The assignment has been added" }, "400": { "description": "Invalid assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "400", "message": "Invalid assignment payload" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "500", "message": "Internal Server Error" } } } } } } }, "/authorization/assignments/{identity_type}/{identity}": { "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "$ref": "#/components/parameters/identity_type" }, { "$ref": "#/components/parameters/identity" } ], "get": { "tags": [ "Authorization" ], "summary": "Get assignment", "description": "Gets the assignment associated with the identity.\n\nThis endpoint requires the permission \"authorization.rbac.read\".\n", "responses": { "200": { "description": "Assignment associated with the identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentData" } } } }, "404": { "description": "Assignment not found for given identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "404", "message": "Assignment not found" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "500", "message": "Internal Server Error" } } } } } }, "patch": { "tags": [ "Authorization" ], "summary": "Update assignment.", "description": "Updates the assignment associated with the identity.\n\nThis endpoint requires the permission \"authorization.rbac.write\".\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentUpdate" } } } }, "responses": { "200": { "description": "Updated assignment associated with identity" }, "404": { "description": "Identity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "404", "message": "Identity not found" } } } }, "409": { "description": "Assignment violates state constraints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "409", "message": "Assignment is invalid" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "500", "message": "Internal Server Error" } } } } } }, "delete": { "tags": [ "Authorization" ], "description": "Removes the assignment associated with the identity and identity_type.\n\nThis endpoint requires the permission \"authorization.rbac.write\".\n", "responses": { "200": { "description": "Assignment is removed." }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "500", "message": "Internal Server Error" } } } } } } }, "/authorization/maintenance": { "get": { "tags": [ "Authorization" ], "description": "Checks whether or not maintenance mode is enabled\n\nThis endpoint requires the permission \"authorization.maintenance.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "Successfully checked maintenance mode", "content": { "text/plain": { "schema": { "type": "string", "properties": { "message": { "type": "string", "enum": [ "true", "false" ] } } } } } }, "401": { "description": "The client is unauthorized" } } }, "post": { "tags": [ "Authorization" ], "description": "Sets whether or not maintenance mode is enabled\n\nThis endpoint requires the permission \"authorization.maintenance.write\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "enabled", "in": "query", "description": "If \"true\", maintenance mode will be enabled; if \"false\", maintenance\nmode will be disabled.\n", "required": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully checked maintenance mode", "content": { "text/plain": { "schema": { "type": "string", "properties": { "message": { "type": "boolean" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" } } } }, "/authorization/permissions": { "get": { "tags": [ "Authorization", "Permissions" ], "description": "Fetches the list of all REST API permissions\n\nThis endpoint requires the permission \"authorization.permissions.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "Successfully retrieved the list of REST API permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" } } } }, "/authorization/roles": { "get": { "summary": "Fetches a list of roles", "description": "This endpoint can be used to view all of the available roles configured\nfor the node. These roles control access to various permissions in the\nsystem.\n\nThis endpoint requires the permission \"authorization.rbac.read\".\n", "tags": [ "Roles", "Permissions", "RBAC", "Authorization" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "offset", "in": "query", "description": "paging offset", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "maximum number of items to return (max 100)", "required": false, "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Successfully retrieved the requested list of roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Roles", "Permissions", "RBAC", "Authorization" ], "summary": "Add a role", "description": "This endpoint can be used to add a new role to the Splinter Role-based\nauthorization system. The role must conform to the role schema and have\nunique \"role_id\" value.\n\nThis endpoint requires the permission \"authorization.rbac.write\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "responses": { "200": { "description": "The role was successfully added" }, "400": { "description": "The request was malformed or the role was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/authorization/roles/{role_id}": { "get": { "summary": "Fetches a role by its ID", "description": "This endpoint can be used to view a specific role.\n\nThis endpoint requires the permission \"authorization.rbac.read\".\n", "tags": [ "Roles" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "role_id", "in": "path", "description": "ID of the role to fetch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the requested role", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Role" } } } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The requested role was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/registry/nodes": { "post": { "summary": "Add a node to the registry", "description": "This endpoint can be used to add a new node to the Splinter registry.\nThe node must be valid (see the Splinter registry documentation for\ndetails on node validity).\n\nThis endpoint requires the permission \"registry.write\".\n", "tags": [ "Splinter Registry" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredNode" } } } }, "responses": { "200": { "description": "The node was successfully added to the registry" }, "400": { "description": "The request was malformed or the node was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List nodes in the registry", "description": "This endpoint can be used to view all or some of the nodes in the\nregistry. If metadata filters are provided via the \"filter\" query\nparameter, only nodes that match the given filters will be returned. See\nthe Splinter registry documentation for details on metadata filters.\n\nThis endpoint requires the permission \"registry.read\".\n", "tags": [ "Splinter Registry" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "offset", "in": "query", "description": "paging offset", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "maximum number of items to return (max 100)", "required": false, "schema": { "type": "integer", "default": 100 } }, { "name": "filter", "in": "query", "description": "url-encodeded stringified JSON containing property filters on the\nnode's metadata properties in the format\n {METADATA_PROPERTY:[{\"operator\":OPERATOR,\"value\":VALUE}]}\n", "required": false, "schema": { "type": "string" }, "example": "%7B%22company%22%3A%5B%22%3D%22%2C%22Cargill%22%5D%7D" } ], "responses": { "200": { "description": "The list of nodes was successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisteredNode" } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "400": { "description": "The request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/registry/nodes/{identity}": { "get": { "summary": "Fetch a node in the registry by its identity", "description": "This endpoint can be used to view a specific nodes in the registry.\n\nThis endpoint requires the permission \"registry.read\".\n", "tags": [ "Splinter Registry" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "identity", "in": "path", "description": "identity of node to fetch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The node was successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RegisteredNode" } } } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The node was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Add or replace a node in the registry", "description": "This endpoint can be used to add a new node to the registry, or replace\nan existing node. When replacing an existing node, the node identity\ncannot be changed. This action is idempotent.\n\nThis endpoint requires the permission \"registry.write\".\n", "tags": [ "Splinter Registry" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "identity", "in": "path", "description": "identity of node to add/replace", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredNode" } } } }, "responses": { "200": { "description": "The node has been added or replaced" }, "400": { "description": "The request was malformed or the node was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a node from the registry", "description": "This endpoint can be used to remove a node from the registry.\n\nThis endpoint requires the permission \"registry.write\".\n", "tags": [ "Splinter Registry" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "identity", "in": "path", "description": "identity of node to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The node has been deleted from the registry" }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The node was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scabbard/{circuit}/{service_id}/batches": { "post": { "summary": "Submit a list of batches to the Scabbard service", "description": "This endpoint can be used to submit batches to a Scabbard service. The\nbody of the request must be a list of valid Sabre batches. If the\nbatches are submitted successfully, the response will contain a link for\nchecking the status of the submitted batches.\n\nThis endpoint requires the permission \"scabbard.write\".\n", "tags": [ "Scabbard" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "circuit", "in": "path", "description": "Circuit the targeted service belongs to", "required": true, "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "description": "ID of the targeted service", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Batch was submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The scabbard service with the given circuit and service id was not\nfound\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests have been made to process batches" }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scabbard/{circuit}/{service_id}/batch_statuses": { "get": { "summary": "Get the statuses of a list of batches", "description": "This endpoint can be used to check the status of one or more batches\nthat were submitted to a Scabbard service. The IDs of the batches to\ncheck should be specified with the `ids` query parameter. The `wait`\nquery parameter requests that the server wait for the given number of\nseconds for the batches to be committed; however, this wait time is not\nguaranteed.\n\nThis endpoint requires the permission \"scabbard.read\".\n", "tags": [ "Scabbard" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "circuit", "in": "path", "description": "Circuit the targeted service belongs to", "required": true, "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "description": "ID of the targeted service", "required": true, "schema": { "type": "string" } }, { "name": "ids", "in": "query", "description": "Comma-separated list of batch IDs", "required": true, "schema": { "type": "string" } }, { "name": "wait", "in": "query", "description": "Time (in seconds) to wait for batches to be committed. If not\nprovided, the server will return the batch statuses immediately. If\nthe parameter is provided without a value, the default time (300\nseconds) will be used.\n", "required": false, "schema": { "type": "integer", "default": 300 } } ], "responses": { "200": { "description": "The statuses of the batches were successfully retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchStatus" } } } } }, "400": { "description": "The request was malformed or no batch IDs were provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The scabbard service with the given circuit and service id was not\nfound\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "The batches were not committed before the specified wait time\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scabbard/{circuit}/{service_id}/state": { "get": { "summary": "Get a list of entries from a Scabbard service's state", "description": "This endpoint can be used to fetch a list of entries from a Scabbard\nservice's state. The entries can be filtered using an address prefix\nprovided with the `prefix` query parameter.\n\nThis endpoint requires the permission \"scabbard.read\".\n", "tags": [ "Scabbard" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "circuit", "in": "path", "description": "Circuit the targeted service belongs to", "required": true, "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "description": "ID of the targeted service", "required": true, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "description": "An address prefix for filtering state entries. If no prefix is\nspecified, all state entries will be returned.\n", "required": false, "schema": { "type": "string", "example": "00ec01" } } ], "responses": { "200": { "description": "The state entries were successfully retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "value": { "type": "array", "items": { "type": "integer" } } } } } } } }, "400": { "description": "The request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The scabbard service with the given circuit and service id was not\nfound\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scabbard/{circuit}/{service_id}/state/{address}": { "get": { "summary": "Get the value at an address in a Scabbard service's state", "description": "This endpoint can be used to fetch the value at a specific address in a\nScabbard service's state.\n\nThis endpoint requires the permission \"scabbard.read\".\n", "tags": [ "Scabbard" ], "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "circuit", "in": "path", "description": "Circuit the targeted service belongs to", "required": true, "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "description": "ID of the targeted service", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address of the value to retrieve from state", "required": true, "schema": { "type": "string", "example": "000000a87cb5eafdcca6a814e4add97c4b517d3c530c2f44b31d18e3b0c44298fc1c14" } } ], "responses": { "200": { "description": "The value was successfully retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer" } } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "The scabbard service with the given circuit and service id was not\nfound, or there is no value at the given address\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/biome/register": { "post": { "tags": [ "Biome" ], "description": "Create new user with username and password credentials", "parameters": [ { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "username": { "description": "username of a new user" }, "hashed_password": { "description": "Hashed password to be used for user authentication\n" } }, "required": [ "username", "hashed_password" ], "example": { "username": "alice@acme.com", "hashed_password": "F4AABE0B40C9ABB8B6FD2EEACB39C965" } } } } }, "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User created successfully" }, "data": { "type": "object", "$ref": "#/components/schemas/BiomeNewUser" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/login": { "post": { "tags": [ "Biome" ], "description": "Authenticates a user with username and password credentials", "parameters": [ { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "username": { "description": "username of user" }, "hashed_password": { "description": "Hashed password to be used for user authentication\n" } }, "required": [ "username", "hashed_password" ], "example": { "username": "alice@acme.com", "hashed_password": "8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Successful login" }, "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" }, "token": { "type": "string", "description": "JWT access token used for authorizing access to protected resources", "example": "Biome:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc" }, "refresh_token": { "type": "string", "description": "JWT refresh token used for obtaining a new access to token", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/logout": { "patch": { "tags": [ "Biome" ], "description": "Removes access tokens associated with a user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User successfully logged out" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/token": { "post": { "tags": [ "Biome" ], "description": "Issues a new access token", "parameters": [ { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "refresh_token": { "description": "a refresh token issues by biome" } }, "required": [ "refresh_token" ], "example": { "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT access token used for authorizing access to protected resources", "example": "Biome:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "401": { "description": "Access token is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "403": { "description": "Refresh token is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/verify": { "post": { "tags": [ "Biome" ], "description": "Verifies a user with username and password credentials", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "username": { "description": "username of user" }, "hashed_password": { "description": "Hashed password to be used for user authentication\n" } }, "required": [ "username", "hashed_password" ], "example": { "username": "alice@acme.com", "hashed_password": "8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Successful verification" }, "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/users": { "get": { "tags": [ "Biome" ], "description": "Lists all users\n\nThis endpoint requires the permission \"biome.user.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "List of users registered in Biome", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "Username used for login", "example": "alice@acme.com" }, "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } } } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/users/{user_id}": { "get": { "tags": [ "Biome" ], "description": "Fetch a user by ID\n\nThis endpoint requires the permission \"biome.user.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "user_id", "in": "path", "description": "ID of the user", "required": true, "schema": { "type": "string", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } ], "responses": { "200": { "description": "User information", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Username used for login", "example": "alice@acme.com" }, "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } }, "put": { "tags": [ "Biome" ], "description": "Update a user\n\nThis endpoint requires the permission \"biome.user.write\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "user_id", "in": "path", "description": "ID of the user", "required": true, "schema": { "type": "string", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "username": { "type": "string", "description": "Existing username of user" }, "hashed_password": { "type": "string", "description": "Hashed password to be used for user authentication\n" }, "new_password": { "type": "string", "description": "Hash of the new password to be used for user authentication\n" }, "new_key_pairs": { "type": "array", "items": { "$ref": "#/components/schemas/BiomeNewUserKey" } } }, "required": [ "username", "hashed_password" ], "example": { "username": "alice@acme.com", "hashed_password": "8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b" } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Credentials and key updated successfully" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BiomeUserKey" } } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } }, "delete": { "tags": [ "Biome" ], "description": "Delete a user\n\nThis endpoint requires the permission \"biome.user.write\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "user_id", "in": "path", "description": "ID of the user", "required": true, "schema": { "type": "string", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User deleted successfully" } } } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "User with {user_id} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/profiles": { "get": { "tags": [ "Biome" ], "description": "List all user profiles\n\nThis endpoint requires the permission \"biome.profile.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "List of profiles for all users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BiomeProfile" } } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/profiles/{user_id}": { "get": { "tags": [ "Biome" ], "description": "Fetch a profile by ID\n\nThis endpoint requires the permission \"biome.profile.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "user_id", "in": "path", "description": "ID of the user", "required": true, "schema": { "type": "string", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } ], "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiomeProfile" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/profile": { "get": { "tags": [ "Biome" ], "description": "Get the profile of the authenticated user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "User's profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiomeProfile" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/keys": { "get": { "tags": [ "Biome" ], "description": "List keys of a user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "User's keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BiomeUserKey" } } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } }, "put": { "tags": [ "Biome" ], "description": "Replace all keys for the user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BiomeUserKey" } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Keys replaced successfully" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } }, "patch": { "tags": [ "Biome" ], "description": "Update a key's display name", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "public_key": { "type": "string", "description": "Public key" }, "new_display_name": { "type": "string", "description": "Updated display name for the key\n" } }, "required": [ "public_key", "new_display_name" ], "example": { "public_key": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118", "new_display_name": "Admin key pair" } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Key updated successfully" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } }, "post": { "tags": [ "Biome" ], "description": "Add a new key for user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiomeUserKey" } } } }, "responses": { "200": { "description": "User added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Key added successfully" }, "data": { "$ref": "#/components/schemas/BiomeUserKey" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/biome/keys/{public_key}": { "get": { "tags": [ "Biome" ], "description": "Fetch key of a user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "public_key", "in": "path", "description": "Public key of the user", "required": true, "schema": { "type": "string", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" } } ], "responses": { "200": { "description": "User's key", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BiomeUserKey" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } }, "delete": { "tags": [ "Biome" ], "description": "Delete key of a user", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "public_key", "in": "path", "description": "Public key of the user", "required": true, "schema": { "type": "string", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" } } ], "responses": { "200": { "description": "User's key deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User deleted successfully" }, "data": { "$ref": "#/components/schemas/BiomeUserKey" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBiome" } } } } } } }, "/oauth/login": { "get": { "tags": [ "OAuth" ], "description": "Provides a redirect to the node's configured OAuth provider to\nauthenticate the user.\n", "parameters": [ { "$ref": "#/components/parameters/protocol_version" }, { "name": "redirect_url", "in": "query", "description": "The URL the client will be redirected to once the OAuth\nauthentication process has been completed. If this parameter is not\nprovided, Splinter will attempt to retrieve the `referer` header\nof the request. If this header value is also not available and the\n`redirect_url` does not have a value, Splinter will respond with\n400 Bad Request.\n", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found redirect", "headers": { "Location": { "description": "URL of the OAuth provider", "schema": { "type": "string" } } } }, "400": { "description": "Request was malformed or no `redirect_url` was provided and the server\nwas unable to retrieve the request's `referer` header value.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/callback": { "get": { "tags": [ "OAuth" ], "description": "Receives an authorization code from the OAuth provider to create an\naccess token for the user. Redirects to a URL provided by the client\nwhen the OAuth authentication process was initiated.\n", "parameters": [ { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "302": { "description": "Splinter has successfully exchanged the authorization code provided\nby the OAuth provider has been successfully exchanged for an access\ntoken. The application may then be redirected to the `redirect_url`\nprovided when the OAuth authentication process was initiated.\nThe `redirect_url` has the access token and other user data required\nto log in the user to the application appended to it as query\nparameters.\n", "headers": { "Location": { "description": "Client URL provided at the beginning of the OAuth authentication\nprocess, with the user's information appended as query parameters.\n", "schema": { "type": "string" } } } }, "400": { "description": "Request was malformed or no authorization request was found correlating\nto the authorization code and the server was unable to retrieve the\nrequest's `referer` header value.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/logout": { "get": { "tags": [ "OAuth" ], "description": "Removes a user's access and refresh tokens from storage.", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User successfully logged out" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/users": { "get": { "tags": [ "OAuth" ], "description": "Lists all OAuth users\n\nThis endpoint requires the permission \"oauth.user.read\".\n", "parameters": [ { "$ref": "#/components/parameters/auth" }, { "$ref": "#/components/parameters/protocol_version" }, { "name": "offset", "in": "query", "description": "paging offset", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "maximum number of items to return (max 100)", "required": false, "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "List of users registered in Biome's OAuth", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthUser" } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "400": { "description": "Request was malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The client is unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "parameters": { "auth": { "name": "Authorization", "in": "header", "description": "The client's authorization, which the server resolves to an identity.\nCurrently supports Biome JWT (if Biome credentials is enabled), Cylinder\nJWT, and OAuth2 bearer tokens.\n", "required": true, "schema": { "type": "string" }, "examples": { "Biome": { "summary": "Biome example", "value": "Bearer Biome:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lk\\ IjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2V\\ sZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD\\ _AEVPEUXY70Ehc" }, "Cylinder": { "summary": "Cylinder example", "value": "Bearer Cylinder:eyJhbGciOiJzZWNwMjU2azEiLCJ0eXAiOiJjeWxpbmR\\ lcitqd3QifQ==.eyJpc3MiOiIwMjc5YmU2NjdlZjlkY2JiYWM1NWEwNjI5NWNlODcwY\\ jA3MDI5YmZjZGIyZGNlMjhkOTU5ZjI4MTViMTZmODE3OTgifQ==.71Vw3+m9R4b8iZU\\ zhRHOAtX/hO5WYA9PgMe27/CeZ6NhIXFYkBBzreoIGpHbfJ8UxT+1MLUgjsQB8TISaf\\ neRA==" }, "OAuth2": { "summary": "OAuth2 example", "value": "Bearer OAuth2:55eeea7ce2b472d69d406990939baa698e34e955" } } }, "protocol_version": { "name": "SplinterProtocolVersion", "in": "header", "description": "The protocol version which the client can understand. If not provided,\nthe node will respond using its latest protocol version.\n", "required": false, "schema": { "type": "integer", "example": 2 } }, "identity_type": { "name": "identity_type", "description": "Enum of possible identity types.", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "key", "user" ] } }, "identity": { "name": "identity", "description": "The unique identity string.", "in": "path", "required": true, "schema": { "type": "string" } }, "paging": { "name": "paging_query", "in": "query", "description": "An offset and limit for paginated results.", "required": true, "schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } }, "schemas": { "BiomeNewUser": { "additionalProperties": false, "properties": { "user_id": { "type": "string" }, "username": { "type": "string" } } }, "Assignment": { "properties": { "identity": { "type": "object", "$ref": "#/components/schemas/Identity" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "AssignmentData": { "properties": { "data": { "type": "object", "$ref": "#/components/schemas/Assignment" } } }, "AssignmentUpdate": { "properties": { "roles": { "type": "array", "items": { "type": "string" } } } }, "AssignmentPayload": { "properties": { "identity": { "type": "object", "$ref": "#/components/schemas/IdentityPayload" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "IdentityPayload": { "properties": { "key": { "type": "string" }, "user": { "type": "string" } } }, "Identity": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "User": { "type": "string" } } }, "Error": { "additionalProperties": false, "properties": { "message": { "description": "A message describing the error that occurred", "type": "string", "example": "DatabaseError({description})" } }, "required": [ "message" ] }, "ErrorBiome": { "additionalProperties": false, "properties": { "code": { "description": "Error code", "type": "string", "example": "400" }, "message": { "description": "A message describing the error that occurred", "type": "string", "example": "Invalid payload" } }, "required": [ "message" ] }, "ErrorResponse": { "additionalProperties": false, "properties": { "code": { "description": "Http response code", "type": "string", "example": "400" }, "message": { "description": "A message describing the error that occurred.", "type": "string", "example": "Invalid query" } } }, "Status": { "additionalProperties": false, "properties": { "version": { "description": "Rest API version", "type": "string", "example": "0.7.1" }, "node_id": { "description": "Node id", "type": "string", "example": "node-009" }, "display_name": { "description": "Human-readable name for the node", "type": "string", "example": "Cargill Node 009" }, "service_endpoint": { "type": "string", "description": "The node's service endpoint", "example": "tcp://foo.bar.biz" }, "network_endpoints": { "description": "The node's locally-bound network endpoints", "type": "array", "items": { "type": "string", "example": "tcp://foo.bar.biz" } }, "advertised_endpoints": { "description": "The node's network endpoints that are publicly accessible", "type": "array", "items": { "type": "string", "example": "tcp://foo.bar.biz" } } }, "required": [ "version" ] }, "ApplicationRegistration": { "additionalProperties": false, "properties": { "status": { "description": "Registration status", "type": "string", "enum": [ "OK", "ERROR" ] }, "circuit_management_type": { "description": "Circuit management type", "type": "string", "example": "gameroom" }, "error_reason": { "description": "Error message if the registration failed", "type": "string" } } }, "RegisteredNode": { "type": "object", "properties": { "identity": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "string" } }, "display_name": { "type": "string" }, "keys": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" } }, "example": { "identity": "node-123123-asdf", "endpoints": [ "tcps://12.0.0.123:8431" ], "display_name": "Cargill - Node 1", "keys": [ "03e0e5086beffc640ec0d149d4f1197fdde0f338afac774541831281c6fd91cbe0" ], "metadata": { "company": "Cargill", "status": "Up" } } }, "Link": { "type": "object", "properties": { "link": { "type": "string", "description": "Link to get status of batches that were submitted", "example": "/scabbard/abcde-01234/ABCD/batch_statuses?ids=6ff35474a572087e08fd6a54d563bd8172951b363e5c9731f1a40a855e14bba45dac515364a08d8403f4fb5d4a206174b7f63c29e4f4e425dc71b95494b8a798" } } }, "BatchStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "The batch's ID", "example": "6ff35474a572087e08fd6a54d563bd8172951b363e5c9731f1a40a855e14bba45dac515364a08d8403f4fb5d4a206174b7f63c29e4f4e425dc71b95494b8a798" }, "status": { "type": "object", "description": "Batch status", "properties": { "statusType": { "type": "string", "enum": [ "Unknown", "Invalid", "Valid", "Pending", "Committed" ] }, "message": { "type": "array", "items": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "f4e147ff464013deccb3e68bb8619beffb29ff86b401257c93bcf8ef76d7ca173fa84b4f4a58414ad2d00a2c9f810cbb726e01cd26ebd44720239d9d35853099" }, "error_message": { "type": "string", "example": "Wasm contract returned invalid transaction: xo, 0.3.3" }, "error_data": { "type": "array", "items": { "type": "integer", "description": "Byte array for arbitrary error data. Each byte is represented as an unsigned integer ranging from 0-255." } } } } } } } } }, "Circuit": { "type": "object", "properties": { "id": { "type": "string", "example": "01234-ABCDE" }, "members": { "description": "Circuit members in the circuit", "type": "array", "items": { "$ref": "#/components/schemas/CircuitMember" } }, "roster": { "description": "All services defined for the circuit", "type": "array", "items": { "$ref": "#/components/schemas/CircuitService" } }, "management_type": { "type": "string", "example": "gameroom" }, "display_name": { "description": "Human readable name for the circuit", "type": "string", "nullable": true }, "circuit_status": { "description": "The status of the circuit", "type": "string", "nullable": true, "enum": [ "Active", "Disbanded", "Abandoned" ] } } }, "CircuitService": { "type": "object", "properties": { "service_id": { "type": "string", "example": "abcd" }, "service_type": { "type": "string", "example": "scabbard" }, "node_id": { "description": "The node ID that is allowed to run this service", "type": "string", "example": "alpha-node-000" } } }, "CircuitMember": { "type": "object", "properties": { "node_id": { "type": "string", "example": "alpha-node-000" }, "endpoints": { "type": "array", "items": { "type": "string", "example": "tcps://12.0.0.123:8431" } }, "public_key": { "type": "string", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" } } }, "Proposal": { "type": "object", "properties": { "proposal_type": { "type": "string", "enum": [ "Create", "UpdateRoster", "AddNode", "RemoveNode", "Disband" ] }, "circuit_id": { "type": "string", "example": "01234-ABCDE" }, "circuit_hash": { "type": "string", "example": "8ce518770b962429a953b10220905ac9adf86a855f0b085695f444edf991b8ca" }, "circuit": { "type": "object", "properties": { "circuit_id": { "type": "string", "example": "01234-ABCDE" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ProposedCircuitMember" } }, "roster": { "type": "array", "items": { "$ref": "#/components/schemas/ProposedCircuitService" } }, "management_type": { "type": "string", "example": "gameroom" }, "application_metadata": { "type": "string", "format": "binary" }, "comments": { "description": "Arbitrary comments to describe the proposed circuit", "type": "string" }, "display_name": { "description": "Human readable name for the circuit", "type": "string", "nullable": true }, "circuit_version": { "description": "The protocol version the circuit adheres to", "type": "integer" }, "circuit_status": { "description": "The status of the circuit", "type": "string", "enum": [ "Active", "Disbanded", "Abandoned" ] } } }, "votes": { "type": "array", "items": { "$ref": "#/components/schemas/Vote" } }, "requester": { "type": "string", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" }, "requester_node_id": { "type": "string", "example": "alpha-node-000" } } }, "ProposedCircuitMember": { "type": "object", "properties": { "node_id": { "type": "string", "example": "alpha-node-000" }, "endpoints": { "type": "array", "items": { "type": "string", "example": "tcps://12.0.0.123:8431" } }, "public_key": { "type": "string", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" } } }, "ProposedCircuitService": { "type": "object", "properties": { "service_id": { "type": "string", "example": "abcd" }, "service_type": { "type": "string", "example": "scabbard" }, "node_id": { "description": "The node ID that is allowed to run this service", "type": "string", "example": "alpha-node-000" }, "arguments": { "description": "Arbitrary arguments to be passed to this service on initialization,\nformatted as an array of (key, value) pairs", "type": "array", "items": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 } } } }, "Vote": { "type": "object", "properties": { "public_key": { "type": "string", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" }, "vote": { "type": "string", "enum": [ "Accept", "Reject" ] }, "voter_node_id": { "type": "string", "example": "alpha-node-000" } } }, "Paging": { "type": "object", "properties": { "current": { "type": "string" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "first": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" }, "last": { "type": "string" } }, "example": { "current": "/registry/nodes?offset=10&limit=10", "offset": 10, "limit": 10, "total": 50, "first": "/registry/nodes?offset=0&limit=10", "prev": "/registry/nodes?offset=0&limit=10", "next": "/registry/nodes?offset=20&limit=10", "last": "/registry/nodes?offset=40&limit=10" } }, "BiomeUserKey": { "type": "object", "properties": { "display_name": { "type": "string", "description": "Display name for key", "example": "Biome Admin Key" }, "encrypted_private_key": { "type": "string", "description": "Encrypted private key", "example": "XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc" }, "public_key": { "type": "string", "description": "Public key", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" }, "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } }, "BiomeNewUserKey": { "type": "object", "properties": { "display_name": { "type": "string", "description": "Display name for key", "example": "Biome Admin Key" }, "encrypted_private_key": { "type": "string", "description": "Encrypted private key", "example": "XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc" }, "public_key": { "type": "string", "description": "Public key", "example": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118" } } }, "BiomeCredentials": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" }, "username": { "type": "string", "description": "Username of a user", "example": "bob@biome.com" } } }, "Permission": { "type": "object", "properties": { "permission_id": { "type": "string", "description": "Unique identifier for the permission", "example": "circuit.read" }, "permission_display_name": { "type": "string", "description": "A human readable name of the permission", "example": "Circuit read" }, "permission_description": { "type": "string", "description": "A helpful description of the permission", "example": "Allows the client to modify circuit state" } } }, "Role": { "type": "object", "properties": { "role_id": { "type": "string", "description": "Unique identifier for the role", "example": "circuit-administrator" }, "display_name": { "type": "string", "description": "A human readable name of the role.", "example": "Circuit Administrator" }, "permissions": { "type": "array", "description": "An array of permissions included with this role.", "items": { "type": "string" } } } }, "BiomeProfile": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" }, "subject": { "type": "string", "description": "Oauth provider's unique identifier for the user", "example": "129367690558975733497" }, "name": { "type": "string", "description": "User's name", "example": "Alice Foo" }, "given_name": { "type": "string", "description": "The given name of the user", "example": "Alice" }, "family_name": { "type": "string", "description": "The family name of the user", "example": "Foo" }, "email": { "type": "string", "description": "The email address of the user", "example": "alice@gmail.com" }, "picture": { "type": "string", "description": "The profile picture for the user's account", "example": "https://lh6.googleusercontent.com/AMZpcempiaceeiA/s96-c/photo.jpg" } } }, "OAuthUser": { "type": "object", "properties": { "subject": { "type": "string", "description": "Oauth provider's unique identifier for the user", "example": "129367690558975733497" }, "user_id": { "type": "string", "description": "Biome's internal unique identifier for the user", "example": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4" } } } } }, "tags": [ { "name": "Biome", "description": "Routes supporting user management in Splinter applications. Optionally compiled." }, { "name": "Proposals" }, { "name": "Admin Service" }, { "name": "Circuits" }, { "name": "Authorization" }, { "name": "Permissions" }, { "name": "Roles" }, { "name": "RBAC" }, { "name": "Splinter Registry" }, { "name": "Scabbard" }, { "name": "OAuth" } ] }