The SSBin service (Secure Static Binary Service) allows for easy secure sharing of binary files and attachments.
To upload we need to allocate first, then upload using the allocationToken.
A backend service can allocate using the plugin, a front-end service needs to use a backend service to allocate, in order for said service to assume ownership.
Most of the time this means that the RED-write Service needs to be used, but use the one that seems to be most applicable.
Example Endpoint to use for allocation: https://write22.red.katedev.com/#allocateDatapointBinaryUpload>
API routes (Click a route to expand it, click here to expand/collapse all)
Default APIs
GET/ ⎘
Provides the API-specification. Only enabled if API exposure is enabled.
Parameter Location Type Requirements Optional Default value Description
format URI-Query string
enum: [ "KateAPI", "InternalAPIMap", "OpenAPI", "Swagger" ]
 Yes "KateAPI" Documentation format. We support KateAPI documentation, Swagger/OpenAPI documentation and raw output of the internal API-map cache.
openApiVersion URI-Query int
enum: [ 2, 3 ]
 Yes 2 Version 3 is crappy with request bodies, so we prefer version 2 (which only sucks regarding Response definitions; hence we prefer KateAPI documentation).
Response HTTP Type Description
Success 200 object The API-documentation.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
LegacyHistory
GET/legacyHistory/{idREDSet} ⎘Authentication required
Get the legacy history for a REDSet.
Parameter Location Type Requirements Optional Default value Description
idREDSet URI-Path string
pattern: ^[a-z0-9]{24}$
 No The REDSet ID which the legacyHistory belongs to.
Response HTTP Type Description
Success 200 array Returns an array with the imported legacy history.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate AND ('red:*' OR 'red:read') ⎘
POST/legacyHistory/{idREDSet} ⎘Authentication required
Stores the legacy history for a REDSet.
Parameter Location Type Requirements Optional Default value Description
idREDSet URI-Path string
pattern: ^[a-z0-9]{24}$
 No The REDSet ID which the legacyHistory belongs to.
legacyHistory POST-body string
format: json
 No The legacy history of a REDSet as json.
Response HTTP Type Description
Success 200 bool Returns true on success.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate:migration ⎘
Main
GET/{fileToken}/{fileName} ⎘
This method serves the actual binary file content.
Parameter Location Type Requirements Optional Default value Description
fileToken URI-Path string
minLength: 1
maxLength: 255
pattern: [A-Za-z0-9_-]+\.[A-Za-z0-9_-]+
 No File token, as part of the file URL.
fileName URI-Path string
minLength: 1
maxLength: 255
 No File name, as part of the file URL.
download URI-Query bool Yes false True if the file should be served as a download (content disposition); false to let the client (browser) decide by mime-type.
returnData URI-Query bool Yes false True if the binary content should be returned as base64-encoded string in a regular JSON API response; false to directly serve the binary file.
imgMaxWidth URI-Query int
min: 0
max: 8000
 Yes 0 Only applies to image extensions. If non-0, image will be scaled to enforce max width and height. If both are specified, that exact size will be output.
imgMaxHeight URI-Query int
min: 0
max: 8000
 Yes 0 Only applies to image extensions. If non-0, image will be scaled to enforce max width and height. If both are specified, that exact size will be output.
imgMaxBytes URI-Query int
min: 0
max: 16777215
 Yes 0 Only applies to image extensions. Max output size in bytes, if feasible. Compression will be increased to meet constraints. 0 (default) indicates no additional compression.
imgMethod URI-Query string
enum: [ "scale", "fill", "crop" ]
 Yes "scale" Only applies to image extensions. If both width and height are specified and do not match original aspect ratio, the image will be either filled (transparent/black), cropped, or scaled to fit both constraints.
imgAllowScaleUp URI-Query bool Yes false If true, allows scaling to a larger size than the original size. If false, the processed image will never be larger than the original.
imgFormat URI-Query string
enum: [ "png", "jpeg" ]
 Yes "png" Only applies to image extensions. Can be used to switch from PNG to JPEG and vice versa.
Response HTTP Type Description
Success 200 string Either serves the binary content directly without an API JSON response (returnData=false, default), or base64-encoded binary content as string.
SSBinUnregisteredSigningServiceException 500 The signing service encoded in the file URL has not been registered/configured on the ssbin-service; so no key-pair is available.
SSBinMalformedFileURLException 400 File URL representing securely stored static binary is malformed/invalid.
SSBinExpiredFileURLException 403 This file URL has expired and is no longer valid. With the proper privileges, it can still be used to issue a new signed file URL.
SSBinInvalidSignatureException 403 This signature of this file URL or request could not be verified, rendering it invalid. The public key used for verification does not match the signature. Note that the filename is also signed.
SSBinRevokedAudienceException 403 This file URL has been revoked; it's intended audience has been blacklisted.
SSBinNotFoundException 404 Binary file content not found.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/{fileToken}/{fileName}/info ⎘
Returns the decoded data that is encoded in a file URL, for analysis.
Parameter Location Type Requirements Optional Default value Description
fileToken URI-Path string
minLength: 1
maxLength: 255
pattern: [A-Za-z0-9_-]+\.[A-Za-z0-9_-]+
 No File token, as part of the file URL.
fileName URI-Path string
minLength: 1
maxLength: 510
 No File name, as part of the file URL.
Response HTTP Type Description
Success 200 array Object with all decoded details about the file URL.
SSBinUnregisteredSigningServiceException 500 The signing service encoded in the file URL has not been registered/configured on the ssbin-service; so no key-pair is available.
SSBinMalformedFileURLException 400 File URL representing securely stored static binary is malformed/invalid.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/{fileToken}/{fileName}/preview ⎘
This method generates a preview of the binary file content.
Parameter Location Type Requirements Optional Default value Description
fileToken URI-Path string
minLength: 1
maxLength: 255
pattern: [A-Za-z0-9_-]+\.[A-Za-z0-9_-]+
 No File token, as part of the file URL.
fileName URI-Path string
minLength: 1
maxLength: 255
 No File name, as part of the file URL.
width URI-Query int
min: 60
max: 8000
 Yes 120 The width of the file preview.
height URI-Query int
min: 60
max: 8000
 Yes 120 The height of the file preview.
scalingMethod URI-Query string
enum: [ "crop", "fill", "scale" ]
 Yes "fill" How to construct the preview
Response HTTP Type Description
Success 200 string Returns a preview based on the given file.
SSBinUnregisteredSigningServiceException 500 The signing service encoded in the file URL has not been registered/configured on the ssbin-service; so no key-pair is available.
SSBinMalformedFileURLException 400 File URL representing securely stored static binary is malformed/invalid.
SSBinExpiredFileURLException 403 This file URL has expired and is no longer valid. With the proper privileges, it can still be used to issue a new signed file URL.
SSBinInvalidSignatureException 403 This signature of this file URL or request could not be verified, rendering it invalid. The public key used for verification does not match the signature. Note that the filename is also signed.
SSBinRevokedAudienceException 403 This file URL has been revoked; it's intended audience has been blacklisted.
SSBinNotFoundException 404 Binary file content not found.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
POST/allocate ⎘
Initializes an upload, and returns an URL to which the file contents can be uploaded.
Parameter Location Type Requirements Optional Default value Description
customer POST-body string
minLength: 1
maxLength: 25
 No ID of the customer that owns this static binary.
department POST-body string
minLength: 1
maxLength: 25
 No ID of the department that owns this static binary.
audience POST-body string
minLength: 1
maxLength: 7
 No Short identifier of the intended audience. Used to potentially blacklist an audience to revoke all tokens issued to said audience. If set to "public", the file is considered unprotected and never expires.
tsExpiry POST-body int No Timestamp (seconds) until when this token should be valid. It will be considered expired afterwards. If audience is set to "public", this must be 0.
service POST-body string
maxLength: 15
 No Name of the microservice owning/signing the resulting file access URL. Its name and keypair must be registered/configured at this ssbin-service.
fileName POST-body string
maxLength: 255
 No Filename of the binary to be uploaded. Note that it will be publicly visible in the file URL and cannot be altered without resigning a new file URL, as it is parted of the signed properties.
signature POST-body string
maxLength: 255
format: byte
 No Base64-encoded signature of the other request parameters, signed by the service identified by the "service" parameter. It is defined as the EdDSA-signature using curve Ed25519 of the string defined by : B64URL( {customer}\n{department}\n{callbackURL}\n{audience}\n{tsExpiry}\n{service}\n{fileName} )
callbackURL POST-body string
maxLength: 511
 Yes "" Optional callback URL to be invoked after the upload is completed. The callback will receive a POST-request with a parameter "fileURL", from which the details can be extracted.
Response HTTP Type Description
Success 200 string URL to which the binary contents can be uploaded to.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
SSBinUnregisteredSigningServiceException 500 The signing service encoded in the file URL has not been registered/configured on the ssbin-service; so no key-pair is available.
SSBinInvalidSignatureException 403 This signature of this file URL or request could not be verified, rendering it invalid. The public key used for verification does not match the signature. Note that the filename is also signed.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
POST/{allocationToken} ⎘
This method processes all URL's returned by "/allocate", and handles the upload of the binary contents. It can be posted using HTTP Files using a file named "content" (using mime-type multipart/form-data) or as regular POST-body in a base64-encoded value of a property "content" (using mimetype multipart/fom-data or application/x-www-form-urlencoded). Additional upload methods might be added later on.
Parameter Location Type Requirements Optional Default value Description
allocationToken URI-Path string
minLength: 1
maxLength: 128
 No This is basically the payload-part of the URI as returned by the call to "/allocate".
Response HTTP Type Description
Success 200 string Signed file URL for this binary. Access and meta-properties are encoded into it, and it is signed with the signing-service' private key.
SSBinInvalidAllocationTokenException 404 The allocated state for this upload token could not be found.
SSBinUploadException 500 The upload of the binary file failed. See details for specific reason.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
POST/{fileToken}/{fileName}/delete ⎘
Hard-deletes the file. Note that this invalidates all tokens. If the exact same file was uploaded twice with different names/origins, all will be deleted since each binary is only stored once.
Parameter Location Type Requirements Optional Default value Description
fileToken URI-Path string
minLength: 1
maxLength: 255
pattern: [A-Za-z0-9_-]+\.[A-Za-z0-9_-]+
 No File token, as part of the file URL.
fileName URI-Path string
minLength: 1
maxLength: 255
 No File name, as part of the file URL.
requestSignature POST-body string
minLength: 1
maxLength: 255
format: byte
 No Base64-encoded signature of the string "{fileToken}/{fileName}/delete", signed by the original signer of the file-URL.
Response HTTP Type Description
Success 200 bool True
SSBinUnregisteredSigningServiceException 500 The signing service encoded in the file URL has not been registered/configured on the ssbin-service; so no key-pair is available.
SSBinMalformedFileURLException 400 File URL representing securely stored static binary is malformed/invalid.
SSBinExpiredFileURLException 403 This file URL has expired and is no longer valid. With the proper privileges, it can still be used to issue a new signed file URL.
SSBinInvalidSignatureException 403 This signature of this file URL or request could not be verified, rendering it invalid. The public key used for verification does not match the signature. Note that the filename is also signed.
SSBinRevokedAudienceException 403 This file URL has been revoked; it's intended audience has been blacklisted.
SSBinNotFoundException 404 Binary file content not found.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Resources
GET/r/{resourceType}/{resourceNameWithExt} ⎘
This serves resources specified by KATE.
Parameter Location Type Requirements Optional Default value Description
resourceType URI-Path string
enum: [ "icon", "image", "energyLabel", "objectType", "compview" ]
 No Type of resource
resourceNameWithExt URI-Path string
minLength: 3
maxLength: 255
pattern: ^[_A-Za-z-0-9]+\.[_A-Za-z-0-9]+$
 No File name, as part of the file URL.
Response HTTP Type Description
Success 200 binary Serves the binary content directly without an API JSON response.
SSBinNotFoundException 404 Binary file content not found.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
_Config
GET/createKeypair ⎘
Generates a new EdDSA-keypair. This method has no side-effects: the keypair is not stored anywhere, and is not service/request dependent.
Response HTTP Type Description
Success 200 array Object with various properties regarding the new EdDSA keypair.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Authentication schemes (Click an authentication scheme to expand it)
JWTAuth
Result wrappers (Click a result-wrapper to expand it)
Success
Error