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 Requires: '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 Requires: '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: 186
    maxLength: 206
    pattern: [A-Za-z0-9_-]{99,119}\.[A-Za-z0-9_-]{86}
    		 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: 186
      maxLength: 206
      pattern: [A-Za-z0-9_-]{99,119}\.[A-Za-z0-9_-]{86}
      		 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: 186
        maxLength: 206
        pattern: [A-Za-z0-9_-]{99,119}\.[A-Za-z0-9_-]{86}
        		 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: 27
            maxLength: 27
            pattern: ^[A-Za-z0-9_-]{27}$
            		 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: 186
              maxLength: 206
              pattern: [A-Za-z0-9_-]{99,119}\.[A-Za-z0-9_-]{86}
              		 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