The Cumulo API

https://{server}/{path}

  • server: required(string)

    The hostname of the server serving the API

  • path: (string)

    The optional API path prefix

Introduction

Cumulo is a hosted key service.

This API documentation describes how to use Cumulo's REST API.

The Cumulo API is a networked REST-like service accessed using the HTTP protocol. All requests must be authenticated.

Authentication

The API is secured using authenticated requests. Requests are authenticated using a JWS bearer access token in the Authorization header of the request.

This access token must be obtained using the OAUTH2 protocol.

Errors

When errors occur the format of the API response body is loosely based on RFC 7807 and contains the following fields:

  • status: The HTTP status code
  • type: The type of error that occurred

The table below lists the error types together with a description of each type.

TypeStatusDescription
authentication-required401The API requests failed the authentication check
invalid-signing-algorithm400The specified signing algorithm is invalid, unknown or, unsupported for the key type
invalid-tbs-length-for-signing-algorithm400The hash/data to be signed is of the invalid length for the selected signature algorithm. Ensure the correct hashing algorithm is used.
item-not-found404The requested API resource does not exist
invalid-2fa-data400The 2FA data supplied is invalid
sad-request/missing-num_signatures400The number of signatures was not specified in the SAD request
sad-request/missing-otp400The SAD request does not have an OTP
sad-request/num_signatures-exceeds-maximum-allowed400The requested number of signatures exceeds the maximum allowed for a SAD authorization
sad-request/num_signatures-less-than-zero400The requested number of signatures is less than zero. It must be a positive integer
sad-request/num_signatures-not-integer400The requested number of signatures is not an integer
signing/sad-invalid-sad400An invalid or non-existent SAD was supplied
signing/sad-expired400The supplied SAD has expired
signing/sad-authorized-signature-count-exceeded400The number of signatures completed using this SAD has reached the limit for this SAD
service-internal-problem500An internal service error occurred. The request can be retried later

/keys

get

get

Get a list of keys

get

get

Get a single key

Get a single key

Secured by oauth2_0

The Cumulo API supports OAuth 2.0 for authenticating API requests

URI Parameters

  • key_id: required(string)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • id: required(string)
  • created_at: required(datetime)

    The date and time at which the key was created

  • public_key: required(object)

    A representation of the public key in JWK format

    • thumbprint: required(string)

      The hash representation of the public key. This can be used to identify or refer to the public key

    • signing_algorithms: required(array of any)

      The signing algorithms that can be used with the key

    Example:

    {
  "id": "ff3fb447-7002-40a2-9c67-88a47bc4c392",
  "created_at": "2022-03-09T14:39:36+02:00",
  "public_key": {
    "kid": "ff3fb447-7002-40a2-9c67-88a47bc4c392",
    "kty": "RSA",
    "key_ops": [
      "sign",
      "decrypt",
      "unwrapKey"
    ],
    "n": "qjQ6wrkM4wcRTIFdhJ_1EjRld2jkXOLUwTqGEzSoEPFPbZ6wvOAOet7Kkr1gwf23eJ-dIcPdfi7iYrYlQl0eV2Zjo6NQFIuBgTOuX0gccDRbLpo8Li47PkNN1soHc5QU5SYqdIbh68hkxFVxmzFwErY0YZ4cu4WIbmzAvr5uZ1dmNw5GetxVNiYjUvvSmAlBbJ1yj4SeuP1T5DV2YU_Igc5uCF5RnPosKbs5FzS22FNQHPRp11a8Uw34yu4t9kGuhG-IyBOb_LA44zwsTLf5zervL8mMPr8BWfBgt7NaxSeL7jv8Rd89K4FtL-2_MNY90nTRVDhn4fPackPpTAPdPw",
    "e": "AAEAAQ"
  },
  "thumbprint": "7evqVtgk-_KnBf0vvZJ4VkDhx6dMUjRn9JpyOdmj2sM",
  "signing_algorithms": [
    "RS256",
    "RS384",
    "RS512"
  ]
}

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    post

    post

    Authorize future signing operations. The returned token must be supplied in the signature request.

    Authorize future signing operations. The returned token must be supplied in the signature request.

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • key_id: required(string)

    Body

    Media type: application/json

    Type: object

    Properties
    • otp: required(string)

      A Time based One Time PIN (TOTP) generated by a compatible app such as Google Authenticator, Microsoft Authenticator, et ce tera.

    • num_signatures: required(integer - minimum: 0)

      The number of signatures to authorise

    Example:

    {
  "otp": "135831",
  "num_signatures": 10
}

    HTTP status code 200

    Body

    Media type: application/json

    Type: object

    Properties
    • sad: required(string)

      The signing activation data (SAD) to use in subsequent signature request API calls.

    • ttl: required(integer)

      The validity period in seconds of the SAD.

    Example:

    {
  "sad": "W-nMIQpbYfTRXam5Y2rESTq8yBsZtnybUg81nY5xWsI",
  "ttl": 900
}

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    post

    post

    Perform a signing operation

    Perform a signing operation

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • key_id: required(string)

    Body

    Media type: application/json

    Possible types:

    • SignatureRequestOtp

      • signing_algorithm: required(one of RS256, RS384, RS512, ES256, ES384, ES512)

        The signing algorithm to use to sign the data. The value depends on the type of key used for signing.

      • tbs: required(string)

        The data to be signed (tbs). This should be the appropriate hash (e.g. SHA256 for RS256 algorithm) of the original document/data that is being signed. The hash should be Base64 URL encoded. If the length of the Base64 decoded hash is invalid for the specified signing algorithm, an error will be returned.

      • otp: required(string)

        A Time based One Time Pin (TOTP) generated by a compatible app such as Google Authenticator, Microsoft Authenticator, et ce tera.

    • SignatureRequestSad

      • signing_algorithm: required(one of RS256, RS384, RS512, ES256, ES384, ES512)

        The signing algorithm to use to sign the data. The value depends on the type of key used for signing.

      • tbs: required(string)

        The data to be signed (tbs). This should be the appropriate hash (e.g. SHA256 for RS256 algorithm) of the original document/data that is being signed. The hash should be Base64 URL encoded. If the length of the Base64 decoded hash is invalid for the specified signing algorithm, an error will be returned.

      • sad: required(string)

        The signing activation data (SAD) token obtained in an earlier authorise request. Note that this token must be unexpired and must not have exhausted its signature count allocation.

    Examples:

    SAD Example:

    {
  "sad": "W-nMIQpbYfTRXam5Y2rESTq8yBsZtnybUg81nY5xWsI",
  "signing_algorithm": "RS256",
  "tbs": "mPm8pUOzr7H6XWiUQdfpIBUwljAvdupVvrBRFDZaKwc="
}

    OTP Example:

    {
  "otp": "166663",
  "signing_algorithm": "RS256",
  "tbs": "mPm8pUOzr7H6XWiUQdfpIBUwljAvdupVvrBRFDZaKwc="
}

    HTTP status code 200

    Body

    Media type: application/json

    Type: object

    Properties
    • signature: required(string)

      The Base64URL encoded signature

    Example:

    {
  "signature": "CSB9PCQak7xjcXpCQ3lLb3tHzwPC5qWcMd63fcRvVtw2ktQfTPyZ9iL4bYmjRcRvAPmN4jVO8VHAtS3H-TGZmPTzO0MHo3m82xpjTlWPcEe-blS-lBcakodic6wMhlm1b4tzjX5sJ94Hh_Zsv_i9Nu13f2WdnewKWEEbvX2vUv5Vft8CSMLEGIyQB7u02oXY2-ntjitR9bTzqR1aiz1Xpry4rgE1uNiVmAtPPtPCAaGJl4fjRFLx_QtrCQN0DqQRe_R_xsawzwsKpBbSi8J50znf_jLW9cZmieVo19xiIA2AqcEJY0Ed1zUoyb9mmpdn7Lqz6FBUr4uUqsrnr2TPSA"
}

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    /certificates

    get

    get

    Get a list of certificates

    get

    get

    Get a single certificate

    Get a single certificate

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • certificate_id: required(string)

    HTTP status code 200

    Body

    Media type: application/json

    Type: object

    Properties
    • id: required(string)
    • created_at: required(datetime)

      The date and time at which the certificate was registered.

    • not_before: required(datetime)

      The date and time from when the certificate is considered valid.

    • not_after: required(datetime)

      The date and time until when the certificate is valid. After this moment the certificate is considered expired.

    • subject: required(string)

      The subject distinguished name (DN) of the certificate.

    • issuer: required(string)

      The issuer (CA) distinguished name of the certificate.

    • serial_number: required(string)

      The serial number of the certificate

    • signing_algorithms: required(array of any)

      The signing algorithms that can be used with the certificate

    Example:

    {
  "id": "9eb2c8ce-f5cd-461b-8153-1fe8dba6512e",
  "name": "cn=Vixis Gashtor,c=ZA",
  "created_at": "2022-06-03T12:40:33+02:00",
  "not_before": "2022-06-03T12:40:29+02:00",
  "not_after": "2023-06-03T12:40:29+02:00",
  "subject": "cn=Vixis Gashtor,c=ZA",
  "issuer": "cn=TrustFactory Test Client Issuing Certificate Authority,ou=TrustFactory PKI Operations,o=TrustFactory(Pty)Ltd,l=Johannesburg,st=Gauteng,c=ZA",
  "serial_number": "910BC50FBF0DE1714B08",
  "key": "d082752d-d8c1-418a-9525-49f4e95f5427",
  "signing_algorithms": [
    "RS256",
    "RS384",
    "RS512"
  ]
}

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    get

    get

    Get the certificate in PEM encoding

    Get the certificate in PEM encoding

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • certificate_id: required(string)

    HTTP status code 200

    Body

    Media type: text/html

    Type: string

    Example:

    -----BEGIN CERTIFICATE-----
MIIGSDCCBDCgAwIBAgILAM4ltU6F+iAdYLEwDQYJKoZIhvcNAQELBQAwgbwxCzAJ
BgNVBAYTAlpBMRAwDgYDVQQIDAdHYXV0ZW5nMRUwEwYDVQQHDAxKb2hhbm5lc2J1
cmcxHTAbBgNVBAoMFFRydXN0RmFjdG9yeShQdHkpTHRkMSQwIgYDVQQLDBtUcnVz
dEZhY3RvcnkgUEtJIE9wZXJhdGlvbnMxPzA9BgNVBAMMNlRydXN0RmFjdG9yeSBU
ZXN0IENsaWVudCBJc3N1aW5nIENlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0yMjAz
MDkxMjQwNTFaFw0yMzAzMDkxMjQwNTFaMCQxIjAgBgkqhkiG9w0BCQEWE2dhc2h0
b3JAZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCq
NDrCuQzjBxFMgV2En/USNGV3aORc4tTBOoYTNKgQ8U9tnrC84A563sqSvWDB/bd4
n50hw91+LuJitiVCXR5XZmOjo1AUi4GBM65fSBxwNFsumjwuLjs+Q03WygdzlBTl
Jip0huHryGTEVXGbMXAStjRhnhy7hYhubMC+vm5nV2Y3DkZ63FU2JiNS+9KYCUFs
nXKPhJ64/VPkNXZhT8iBzm4IXlGc+iwpuzkXNLbYU1Ac9GnXVrxTDfjK7i32Qa6E
b4jIE5v8sDjjPCxMt/nN6u8vyYw+vwFZ8GC3s1rFJ4vuO/xF3z0rgW0v7b8w1j3S
dNFUOGfh89pyQ+lMA90/AgMBAAGjggHgMIIB3DAJBgNVHRMEAjAAMB0GA1UdDgQW
BBRGiGxLd9EqXOxQ6lgR/zRgtQ+0LTAfBgNVHSMEGDAWgBQrvVJzUMU4bbHRpiyu
8vQeR9C+XjAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUHAwQwHgYD
VR0RBBcwFYETZ2FzaHRvckBleGFtcGxlLmNvbTCBoAYIKwYBBQUHAQEEgZMwgZAw
PgYIKwYBBQUHMAGGMmh0dHA6Ly9zdGctb2NzcC50cnVzdGZhY3RvcnkubmV0L3Rm
LWNsaWVudC1pc3N1aW5nME4GCCsGAQUFBzAChkJodHRwOi8vc3RnLXByLXdlYi50
cnVzdGZhY3RvcnkubmV0L3JlcG9zaXRvcnkvdGYtb25saW5lLWNsaWVudC5jcnQw
UAYDVR0fBEkwRzBFoEOgQYY/aHR0cDovL3N0Zy1wci13ZWIudHJ1c3RmYWN0b3J5
Lm5ldC9jcmwvdGYtY2xpZW50LXN1YnNjcmliZXIuY3JsMFUGA1UdIAROMEwwSgYK
KwYBBAGDiQ4CBDA8MDoGCCsGAQUFBwIBFi5odHRwczovL3N0Zy1wci13ZWIudHJ1
c3RmYWN0b3J5Lm5ldC9yZXBvc2l0b3J5MA0GCSqGSIb3DQEBCwUAA4ICAQAdokba
Rw7HMgEunqqG0eT1Op4tzma/WIReWWkigb4G+5MR5IfrdEpeTX6c6MhEh2l3N5uL
bBoip0S+mDlst9x4ny3Uz+GrdOSF2YHfVfnvEIlKMwZx6zaRVAxnUjLKmsQ6sDeR
pblur3DPq+gdurll/xPu+CGGy/KZ2sUAAAyqWBQ1z4NDYzJibkh4X3brO9oyCdFn
lk+qhyIMgSa9Q8KRbHl/Nlq5NRTRi3H48Li94UX6dnpr9O1OX8J9eklA8HtpfOhz
oNoRtH+pgdWcfcdjbQuaMYCWNoZqkqqdNkKNKu3ahkG4eweW8THUsuJ1u+JsXHwD
8HUfXlvRI+KZrAg+W8cQmczSNsCx4BlzNQkah6w0JN95sg7ZKj6nDxf6rrooS9Ri
KrRvhSp2E25+C+xc7BncZidDGH1FraOnW+atJpKemoXTU8pJ1T9rLrZrX6/0wYoi
JihnRnfUINeGEOA8ZvB8HQKy7vUtA8d9JuLxURxsK+XTascdwDmAAC6psavkiv69
iOOvIBK4OMWwEKM/tLZJgmId88tH6SE9dZ/1FUNpPLd/NpKQNbLCByUOOW9dwOxF
qiBXYRpQwM7V5Vby+Ry0htfDI+9X1SI0Vve16TK+OA3lAfL9vWJRd0qC8nmUBQfX
0cx4KtsH8oqhdyW+cSMAPBFgQt/NayRKni9bdQ==
-----END CERTIFICATE-----

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    get

    get

    Get the certificate signing chain in PEM encoding. This will omit the root CA certificate.

    Get the certificate signing chain in PEM encoding. This will omit the root CA certificate.

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • certificate_id: required(string)

    Query Parameters

    • return: (string)

      The type of certifificate to include in the chain. Valid values are 'leaf', 'intermediate', 'root' and 'all'. You may specify more than one type of certificate to include in the chain. If you specify multiple types then the values must be delimited using the pipe character ('|'). If you do not specify this parameter then only the intermediate CA certificates will be returned.

      Typical examples are:

      all: To return all certificates in the chain including end entity and root certificates

      leaf|intermediate: To return the end entity certificate and the intermediate CA certificates

      intermediate|root: To return the intermediate and root CA certificates

      Example:

      leaf|intermediate

    HTTP status code 200

    Body

    Media type: text/html

    Type: string

    Example:

    -----BEGIN CERTIFICATE-----
MIIHRDCCBSygAwIBAgIQUftmxzaJ6XS2YYJILdlqOTANBgkqhkiG9w0BAQsFADCB
tDELMAkGA1UEBhMCWkExEDAOBgNVBAgMB0dhdXRlbmcxFTATBgNVBAcMDEpvaGFu
bmVzYnVyZzEdMBsGA1UECgwUVHJ1c3RGYWN0b3J5KFB0eSlMdGQxJDAiBgNVBAsM
G1RydXN0RmFjdG9yeSBQS0kgT3BlcmF0aW9uczE3MDUGA1UEAwwuVHJ1c3RGYWN0
b3J5IENsaWVudCBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0xNzEyMDUx
MjM2MjRaFw0zMjEyMDExMjM2MjRaMIG3MQswCQYDVQQGEwJaQTEQMA4GA1UECAwH
R2F1dGVuZzEVMBMGA1UEBwwMSm9oYW5uZXNidXJnMR0wGwYDVQQKDBRUcnVzdEZh
Y3RvcnkoUHR5KUx0ZDEkMCIGA1UECwwbVHJ1c3RGYWN0b3J5IFBLSSBPcGVyYXRp
b25zMTowOAYDVQQDDDFUcnVzdEZhY3RvcnkgQ2xpZW50IElzc3VpbmcgQ2VydGlm
aWNhdGUgQXV0aG9yaXR5MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA
saLhEFHXdzZyJsh2BTCc6wkUFLMrjsL8EivpfjRO4FriiH/gPIJHQI9l75NyK55m
s49ECLz00gtKPMhcF37EZB2wL+Irodsf48nSmLTBqt1ZOPb5jdRkd6i6dP4wM7Sd
nWsUyl/EmpOB8kM3R+3wxxxEXxzkrqApDDRPojTv/MYwVeFFe9/CFojHN9f+SvZa
XYYrrPMRHMuGffcfJIB6Ps2CigUcMnbf0EYFfluCpMXBI0VOZlVw6iR4AefJoNMt
XW3r+m16I95BU6YLjgF6hTX70vbBMYtMkJ9YEYLwPam7xd38Ndb2yBLT/wo3b8bI
Yr+OYtIJfHcbKPgL8na5abhyBRGYuWgBu68HaMxTChgtLG7l6nPQsCEnJJnnivQH
TKC9rMGrnbkwO8HUyoJm6XH6nnraPM/dQtQG13cbRhNgVEQOKUJsX1aFKqm/GQ5O
BI+mQBTnWQtup9QqEbSUSE51pOXYjdokCkpCR8d83KgR+rl7Jzr5U7h35adk1KP+
e9lL6N6mJ+A+j5BdBBQ7sv+KDJQxjZaX/Io18uHVAP88bA0LeZIU6BDqUiUuMvgL
fKbPNiF2zROdPU1Uvxg0gkRQCZQrE06L/hU0KUwk8ztMIOOeSADII4AVxYZot0ry
Tjfes9+7LTLssEi66RYsets87yZC6/UEdeudk6aQAc0CAwEAAaOCAUswggFHMB0G
A1UdDgQWBBSZ5m/2B7tt3ta6QTqu1Z53qbN63zAfBgNVHSMEGDAWgBQ8tpw4Wuy1
1CILQL5jDwiLKO4MGTASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIB
hjBKBggrBgEFBQcBAQQ+MDwwOgYIKwYBBQUHMAGGLmh0dHA6Ly9vY3NwLnRydXN0
ZmFjdG9yeS5uZXQvdGYtY2xpZW50LWlzc3VpbmcwRgYDVR0fBD8wPTA7oDmgN4Y1
aHR0cDovL3d3dy50cnVzdGZhY3RvcnkubmV0L2NybC90Zi1jbGllbnQtaXNzdWlu
Zy5jcmwwTQYDVR0gBEYwRDBCBgkrBgEEAYOJDgEwNTAzBggrBgEFBQcCARYnaHR0
cHM6Ly93d3cudHJ1c3RmYWN0b3J5Lm5ldC9yZXBvc2l0b3J5MA0GCSqGSIb3DQEB
CwUAA4ICAQCSOMlA+kFFAKTzIJQLtTwUfS2mn+bvj2j4notdZpVzSGFfzWMrZ9bp
9RSA9RE/Irb2iFerTcv46PJFZdcpW4xJtcvP8z1pw1W1hoihineY7+9wIuxCEF/O
Ek2WY1ohyXC/qeHYIVGcYbzhu1wwKF8V7//+EBQQ4K4oJtaRVeL5BMitx090iB7l
Hr9LYzMrXCeGvR4VEvmDD/wYo+xXlA40cfoKoTbH8LGYjebrCzdnFrkBL/gLEHI1
jT/tXm/PqfdlTFFKpjX36kPEfUZfR474Io3Yz8t0DwNxNa1NQAs69qhRrfdeywN/
Dc03tSnhyMxSyhws7N1/DV3nMcfKgzD43TzGbdweiLWKH5duoRZSfI5ZbGbXyr8r
AzjemkmVoba1aGan7KuLtrwGP905enhfZASppZZjWjDzFYRqGBUAqsZQqn1XKeiy
CPl20Eo748N40/GRQ9ol5RJESegGK6FC+ayxs1PH2X0pYIsp73Wg6lxTk2Njj3pg
IfTe97Cb/meJIuDQixWcK9Ha45JBUwfgmHby5TJIpK3oCs87Kbk/sIUae/6MqVIZ
EsDD3szsc0xzBmKNuIke6LtvrhjK8wE1C2JophNgI2Awa5IpIT1fqQ8/nzSHfTDc
W1vcNuaG1cIN5JhaKcI35Uv4RANhMmd+QCnSfxsAUzMLAcWkKgbR0g==
-----END CERTIFICATE-----

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    post

    post

    Authorize future signing operations. The returned token must be supplied in the signature request.

    Authorize future signing operations. The returned token must be supplied in the signature request.

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • certificate_id: required(string)

    Body

    Media type: application/json

    Type: object

    Properties
    • otp: required(string)

      A Time based One Time PIN (TOTP) generated by a compatible app such as Google Authenticator, Microsoft Authenticator, et ce tera.

    • num_signatures: required(integer - minimum: 0)

      The number of signatures to authorise

    Example:

    {
  "otp": "135831",
  "num_signatures": 10
}

    HTTP status code 200

    Body

    Media type: application/json

    Type: object

    Properties
    • sad: required(string)

      The signing activation data (SAD) to use in subsequent signature request API calls.

    • ttl: required(integer)

      The validity period in seconds of the SAD.

    Example:

    {
  "sad": "W-nMIQpbYfTRXam5Y2rESTq8yBsZtnybUg81nY5xWsI",
  "ttl": 900
}

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions

    post

    post

    Perform a signing operation

    Perform a signing operation

    Secured by oauth2_0

    The Cumulo API supports OAuth 2.0 for authenticating API requests

    URI Parameters

    • certificate_id: required(string)

    Body

    Media type: application/json

    Possible types:

    • SignatureRequestOtp

      • signing_algorithm: required(one of RS256, RS384, RS512, ES256, ES384, ES512)

        The signing algorithm to use to sign the data. The value depends on the type of key used for signing.

      • tbs: required(string)

        The data to be signed (tbs). This should be the appropriate hash (e.g. SHA256 for RS256 algorithm) of the original document/data that is being signed. The hash should be Base64 URL encoded. If the length of the Base64 decoded hash is invalid for the specified signing algorithm, an error will be returned.

      • otp: required(string)

        A Time based One Time Pin (TOTP) generated by a compatible app such as Google Authenticator, Microsoft Authenticator, et ce tera.

    • SignatureRequestSad

      • signing_algorithm: required(one of RS256, RS384, RS512, ES256, ES384, ES512)

        The signing algorithm to use to sign the data. The value depends on the type of key used for signing.

      • tbs: required(string)

        The data to be signed (tbs). This should be the appropriate hash (e.g. SHA256 for RS256 algorithm) of the original document/data that is being signed. The hash should be Base64 URL encoded. If the length of the Base64 decoded hash is invalid for the specified signing algorithm, an error will be returned.

      • sad: required(string)

        The signing activation data (SAD) token obtained in an earlier authorise request. Note that this token must be unexpired and must not have exhausted its signature count allocation.

    Examples:

    SAD Example:

    {
  "sad": "W-nMIQpbYfTRXam5Y2rESTq8yBsZtnybUg81nY5xWsI",
  "signing_algorithm": "RS256",
  "tbs": "mPm8pUOzr7H6XWiUQdfpIBUwljAvdupVvrBRFDZaKwc="
}

    OTP Example:

    {
  "otp": "166663",
  "signing_algorithm": "RS256",
  "tbs": "mPm8pUOzr7H6XWiUQdfpIBUwljAvdupVvrBRFDZaKwc="
}

    HTTP status code 200

    Body

    Media type: application/json

    Type: object

    Properties
    • signature: required(string)

      The Base64URL encoded signature

    Example:

    {
  "signature": "CSB9PCQak7xjcXpCQ3lLb3tHzwPC5qWcMd63fcRvVtw2ktQfTPyZ9iL4bYmjRcRvAPmN4jVO8VHAtS3H-TGZmPTzO0MHo3m82xpjTlWPcEe-blS-lBcakodic6wMhlm1b4tzjX5sJ94Hh_Zsv_i9Nu13f2WdnewKWEEbvX2vUv5Vft8CSMLEGIyQB7u02oXY2-ntjitR9bTzqR1aiz1Xpry4rgE1uNiVmAtPPtPCAaGJl4fjRFLx_QtrCQN0DqQRe_R_xsawzwsKpBbSi8J50znf_jLW9cZmieVo19xiIA2AqcEJY0Ed1zUoyb9mmpdn7Lqz6FBUr4uUqsrnr2TPSA"
}

    HTTP status code 400

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(one of authentication-required, invalid-2fa-data, 2fa-totp-reuse, invalid-signing-algorithm, invalid-tbs-length-for-signing-algorithm, item-not-found, sad-request/missing-num_signatures, sad-request/missing-otp, sad-request/num_signatures-exceeds-maximum-allowed, sad-request/num_signatures-less-than-zero, sad-request/num_signatures-not-integer, signing/sad-invalid-sad, signing/sad-expired, signing/sad-authorized-signature-count-exceeded, service-internal-problem)

      The type of error that occurred

    HTTP status code 401

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(authentication-required)

      The type of error that occurred

    HTTP status code 403

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(access-denied)

      The type of error that occurred

    HTTP status code 404

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(item-not-found)

      The type of error that occurred

    HTTP status code 500

    Body

    Media type: application/json

    Type: object

    Properties
    • status: required(integer)

      The HTTP status code. This should match the value of the code in the HTTP Status header.

    • type: required(service-internal-problem)

      The type of error that occurred

    Secured by oauth2_0

    Headers

    • Authorization: required(string)

      Use to send a valid OAuth 2 access token. The token must be prefixed with 'Bearer '.

      Example:

      Bearer oitr7g4fp1-kjt294j

    HTTP status code 401

    Bad or expired token. This can happen if the API consumer uses a revoked or expired access token. You should re-authenticate the user if you get this response.

    HTTP status code 403

    Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...) or tried to access resources for which the supplied access token has no permissions