{ "openapi": "3.1.0", "info": { "title": "Fireblocks - Securosys Custom Server", "description": "The Securosys Custom Server enables your Fireblocks workspace to use keys that\nare securely stored in a Primus HSM.\nThe Securosys Custom Server sits between the Fireblocks Key Link Agent and the Securosys Transaction Security Broker,\nand translates requests between them.\n\nFor details, view the [online documentation](https://docs.securosys.com/fireblocks/overview/).\n\n[Securosys End-User License Agreement (EULA)](https://www.securosys.com/eula) \n", "contact": { "name": "Securosys SA", "url": "https://www.securosys.com/en/contactus", "email": "info@securosys.ch" }, "license": { "name": "Securosys License", "url": "https://www.securosys.com/en/about/securosys-general-terms-and-conditions" }, "version": "1.0.1" }, "servers": [ { "url": "http://localhost:8080", "description": "Generated server url" } ], "tags": [ { "name": "Securosys Custom Server", "description": "The primary endpoints, required by the Fireblocks Key Link API specification. Used for submitting signing requests, polling their status, and re-trying them." }, { "name": "Helper Functions", "description": "Helper functions for creating validation keys and asset keys (signing keys)." } ], "paths": { "/v1/validationAndProofOfOwnership": { "post": { "tags": [ "Helper Functions" ], "summary": "Create validation and Proof of Ownership", "description": "Creates a validation certificate and a signed Proof of Ownership in a single request. See also the separate endpoints.", "operationId": "validationAndProofOfOwnership", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProofOfOwnershipRequest" } } }, "required": true }, "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProofOfOwnershipResponse" } } } } } } }, "/v1/signRequest/{requestId}": { "post": { "tags": [ "Securosys Custom Server" ], "summary": "Retry single pending message", "description": "Sends a pending message by request ID (that is cached in the database) once again to the TSB for signing.", "operationId": "signRequest", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesStatusResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/signAllPendingMessages": { "post": { "tags": [ "Securosys Custom Server" ], "summary": "Retry all pending messages", "description": "Sends all pending messages (that are cached in the database) once again to the TSB for signing.", "operationId": "signAllPendingMessages", "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation" } }, "security": [ { "api_key": [] } ] } }, "/v1/proofOfOwnership": { "post": { "tags": [ "Helper Functions" ], "summary": "Create Proof of Ownership", "description": "Generates a signed Proof of Ownership message, thus confirming control over the private asset key (in Fireblocks' terms: signing key).", "operationId": "proofOfOwnership", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOfOwnershipRequest" } } }, "required": true }, "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOfOwnershipResponse" } } } } } } }, "/v1/messagesToSign": { "post": { "tags": [ "Securosys Custom Server" ], "summary": "Sign message", "description": "Sends new messages to the HSM for signing. The Fireblocks Agent calls this when it requires something to be signed. The request is persisted to the database, and forwarded to the TSB. The result is stored in the database. ", "operationId": "messagesToSign", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" } } } }, "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/messagesStatus": { "post": { "tags": [ "Securosys Custom Server" ], "summary": "Get message status", "description": "Query the status of the messages that were previously submitted to be signed. These signatures may already be ready or may still be pending. The Fireblocks Agent polls this endpoint.", "operationId": "messagesStatus", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesStatusRequest" } } }, "required": true }, "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesStatusResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/createValidations": { "post": { "tags": [ "Helper Functions" ], "summary": "Create validation certificate", "description": "Creates a validation certificate. The certificate is signed by the validation key. The public key that is certified is the provided asset key (in Fireblocks' terms: signing key). Prerequisite: the validation key with label \"FIREBLOCKS_VALIDATION_KEY\" must exist.", "operationId": "createValidations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateValidationsRequest" } } }, "required": true }, "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateValidationResponse" } } } } } } }, "/v1/createValidationKey": { "post": { "tags": [ "Helper Functions" ], "summary": "Create validation key", "description": "Creates key that can be used as the validation key. The key label is the fixed value \"FIREBLOCKS_VALIDATION_KEY\". Returns the public key in PEM format. Onboard this public key to your Fireblocks workspace.", "operationId": "createValidationKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateValidationKeyRequest" } } }, "required": true }, "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "201": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateValidationKeyResponse" } } } } } } }, "/v1/versionInfo": { "get": { "tags": [ "Service Information" ], "summary": "Get version", "description": "Returns the version of the service.", "operationId": "getVersionInfo", "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/v1/logs": { "get": { "tags": [ "Service Information" ], "summary": "Get logs", "description": "Returns the backend logs of the service.", "operationId": "getLogs", "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } } } }, "/v1/hsmConnectionCheck": { "get": { "tags": [ "Helper Functions" ], "summary": "Check TSB/HSM connectivity", "description": "Calls the TSB /v1/licenseInfo endpoint to verify connectivity to the TSB and the HSM. Returns the license flags of the HSM partition.", "operationId": "checkConnection", "responses": { "400": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "403": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "501": { "description": "Implementation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonBasedExceptionDto" } } } }, "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } } } } } } } }, "components": { "schemas": { "ReasonBasedExceptionDto": { "type": "object", "description": "Response for a specific error when an operation can not be completed successfully.", "properties": { "errorCode": { "type": "integer", "format": "int32", "description": "The code of the error." }, "reason": { "type": "string", "description": "The reason for the error." }, "message": { "type": "string", "description": "The message containing why the error was returned by the application." } } }, "ValidationProofOfOwnershipRequest": { "type": "object", "properties": { "assetKeyName": { "type": "string" }, "assetKeyAlgorithm": { "type": "string", "description": "The algorithm of the asset key.", "enum": [ "EC", "ED" ], "example": "EC" }, "workspaceDisplayName": { "type": "string" }, "sdkApiKey": { "type": "string" }, "agentUserId": { "type": "string" }, "isSkaKey": { "type": "boolean", "description": "If true the asset key is an SKA key with policy." } }, "required": [ "agentUserId", "assetKeyAlgorithm", "assetKeyName", "sdkApiKey", "workspaceDisplayName" ] }, "Proof": { "type": "object", "properties": { "message": { "type": "string" }, "signature": { "type": "string" } } }, "ValidationProofOfOwnershipResponse": { "type": "object", "properties": { "signingDeviceKeyId": { "type": "string" }, "signedCertPem": { "type": "string" }, "agentUserId": { "type": "string" }, "proofOfOwnership": { "$ref": "#/components/schemas/Proof" } } }, "MessageResponse": { "type": "object", "properties": { "signedMessages": { "type": "array", "items": { "$ref": "#/components/schemas/SignedMessage" } } } }, "MessageStatus": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "KEY_LINK_PROOF_OF_OWNERSHIP_RESPONSE", "KEY_LINK_TX_SIGN_RESPONSE" ] }, "status": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "response": { "$ref": "#/components/schemas/MessageResponse" } }, "required": [ "requestId", "response", "status", "type" ] }, "MessagesStatusResponse": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/MessageStatus" } } }, "required": [ "statuses" ] }, "SignedMessage": { "type": "object", "properties": { "message": { "type": "string" }, "index": { "type": "integer", "format": "int32" }, "signature": { "type": "string" } }, "required": [ "index", "message", "signature" ] }, "ProofOfOwnershipRequest": { "type": "object", "properties": { "assetKeyName": { "type": "string", "minLength": 1 }, "assetKeyAlgorithm": { "type": "string", "description": "The algorithm of the asset key.", "enum": [ "EC", "ED" ], "example": "EC", "minLength": 1 }, "workspaceDisplayName": { "type": "string", "minLength": 1 }, "sdkApiKey": { "type": "string", "minLength": 1 } }, "required": [ "assetKeyAlgorithm", "assetKeyName", "sdkApiKey", "workspaceDisplayName" ] }, "ProofOfOwnershipResponse": { "type": "object", "properties": { "proofOfOwnership": { "$ref": "#/components/schemas/Proof" }, "timestamp": { "type": "integer", "format": "int64" } } }, "Message": { "type": "object", "properties": { "payloadSignatureData": { "$ref": "#/components/schemas/PayloadSignatureData" }, "payload": { "type": "string" } }, "required": [ "payload", "payloadSignatureData" ] }, "MessageEnvelope": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "transportMetadata": { "$ref": "#/components/schemas/TransportMetadata" } }, "required": [ "message", "transportMetadata" ] }, "MessagesRequest": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEnvelope" } } }, "required": [ "messages" ] }, "PayloadSignatureData": { "type": "object", "properties": { "signature": { "type": "string" }, "service": { "type": "string" } }, "required": [ "service", "signature" ] }, "TransportMetadata": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "KEY_LINK_PROOF_OF_OWNERSHIP_REQUEST", "KEY_LINK_TX_SIGN_REQUEST" ] } }, "required": [ "requestId", "type" ] }, "MessagesStatusRequest": { "type": "object", "properties": { "requestsIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "requestsIds" ] }, "CreateValidationsRequest": { "type": "object", "description": "Create Validations request.", "properties": { "assetKeyName": { "type": "string", "minLength": 1 }, "assetKeyAlgorithm": { "type": "string", "description": "The algorithm of the asset key.", "enum": [ "EC", "ED" ], "example": "EC", "minLength": 1 }, "isSkaKey": { "type": "boolean", "default": false, "description": "If true the asset key is an SKA key with policy." } }, "required": [ "assetKeyAlgorithm", "assetKeyName" ] }, "CreateValidationResponse": { "type": "object", "properties": { "certificate": { "type": "string" } } }, "CreateValidationKeyRequest": { "type": "object", "description": "Create validation key request.", "properties": { "algorithm": { "type": "string", "description": "The algorithm with which the key should be created. By default it will be RSA.", "enum": [ "EC", "ED", "RSA" ], "example": "RSA" }, "curveOid": { "type": "string", "description": "The oid of the curve used for the EC or ED algorithm. Mandatory if chosen algorithm is set to EC or ED. secp224k1: 1.3.132.0.32\nsecp224r1: 1.3.132.0.33\nsecp256k1: 1.3.132.0.10\nsecp256r1 (also known as P-256 or prime256v1): 1.2.840.10045.3.1.7\nsecp384r1 (also known as P-384): 1.3.132.0.34\nsecp521r1 (also known as P-521): 1.3.132.0.35\nx962p239v1: 1.2.840.10045.3.1.1\nx962p239v2: 1.2.840.10045.3.1.2\nx962p239v3: 1.2.840.10045.3.1.3\nbrainpool224r1: 1.3.36.3.3.2.8.1.1.1\nbrainpool256r1: 1.3.36.3.3.2.8.1.1.7\nbrainpool320r1: 1.3.36.3.3.2.8.1.1.9\nbrainpool384r1: 1.3.36.3.3.2.8.1.1.11\nbrainpool512r1: 1.3.36.3.3.2.8.1.1.13\nfrp256v1: 1.2.250.1.223.101.256.1\nEd25519: 1.3.101.112" }, "keySize": { "type": "integer", "format": "int32", "description": "The length of the key. Only applicable for RSA. By default it will be 2048.", "example": 2048 } } }, "CreateValidationKeyResponse": { "type": "object", "properties": { "publicKeyPem": { "type": "string" } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "description": "Set your API Key.", "name": "Authorization", "in": "header" } } } }