Select release
On this page:

Signer Cloud API

Edit on Github Send Feedback develop

Signer Cloud Server provides a RESTful API that allows to control specific parts of the signing process.

Error Handling

Signer Cloud Server uses following format for error response body, accompanied by an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down), following ERROR codes may be returned:

Error Code HTTP Code Description
ERROR_UNAUTHORIZED 401 Unauthorized request
REQUEST_VALIDATION_ERROR 400 REST API endpoint called with invalid body or parameters
ERROR_RESOURCE_NOT_FOUND 400 Resource is not found
CERTIFICATE_PROCESSING_ERROR 500 Issue with processing the certificate
CSR_INVALID_SIGNATURE_ERROR 400 Error when signature of CSR (Certificate Signing Request) is invalid
CSR_SIGNATURE_VERIFICATION_ERROR 503 Error when signature of CSR (Certificate Signing Request) could not be verified. Can indicates problem with Power Auth server
CERTIFICATE_AUTHORITY_ERROR 400,503 Error returned from Certificate Authority. 4xx errors are mapped to 400, and 5xx errors are mapped to 503. Can indicate problem with Certificate Authority server
DOCUMENT_UPLOAD_ERROR 400 Error when Document content could not be uploaded
DOCUMENT_INVALID_SIGNATURE_ERROR 400 Error when signature of Document is invalid
DOCUMENT_SIGNING_ERROR 500 Error when the content of a signed Document could not be assembled
ILLEGAL_OPERATION_ERROR 400 The state of the resource does not allow the requested operation
DOCUMENT_VISUAL_SIGNATURE_ERROR 400 Visual signature is invalid for Document
ERROR_GENERIC 400 Any other error not covered by a specific error code

All error responses that are produced by the Signer Cloud Server have the following body:

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "An error message"
  }
}

API Endpoints

post /signers Create New Signer

Create new signer and enroll for new certificate using CSR. System will track certificate expiration and starts auto-renewal job.

Request

{
  "signerId": "456def",
  "userId" : "123abc",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\ncontent\nwith\ncorrect\nline\nendings\n-----END CERTIFICATE REQUEST-----",
}
Request Params
Attribute Type Description
signerId String Activation ID (Registration ID) from PowerAuth.
userId String Custom User ID mostly for tracking purposes.
csr String PEM encoded PKCS10 CSR, one line, line endings \n.

Response

200 OK

put /signers/{signerId} Change Signer Status

Change the status of an existing signer (e.g., activate, deactivate, suspend) identified by signerId.

Request

{
  "signerStatus": "REVOKED",
  "revocationReason": "UNSPECIFIED"
}
Request Params
Attribute Type Description
signerId String Activation ID (Registration ID) from PowerAuth.
signerStatus String Select new signer status. ENUM: ACTIVE, BLOCKED, REMOVED, REVOKED, EXPIRED
revocationReason String Optional parameter, used only if signerStatus is set to REVOKED. It specifies the reason for revocation, which is passed to EJBCA. If not provided, the default value UNSPECIFIED is used. ENUM: NOT_REVOKED, UNSPECIFIED, KEY_COMPROMISE, CA_COMPROMISE, AFFILIATION_CHANGED, SUPERSEDED, CESSATION_OF_OPERATION, CERTIFICATE_HOLD, REMOVE_FROM_CRL, PRIVILEGES_WITHDRAWN, AA_COMPROMISE

Response

200 OK

get /signers/{signerId} Signer Details

Get signer state.

Request

Request without body.

Request Params
Attribute Type Description
signerId String Activation ID (Registration ID) from PowerAuth.

Response

{
  "signerId": "123abc",
  "userId": "123abc",
  "signerStatus": "ACTIVE"
}
Attribute Type Description
signerId String Activation ID (Registration ID) from PowerAuth.
userId String Custom User ID mostly for tracking purposes.
signerStatus String Signer status. ENUM: ACTIVE, BLOCKED, REMOVED, REVOKED, EXPIRED

post /documents Upload Document

Upload document as one file using multipart/form-data. Maximum file size depends on server configuration.

Request

Upload via Multipart Requests File Upload.

POST /documents/upload
Host: example.com
Content-Length: {size}
Content-Type: multipart/form-data; boundary=abcde12345

--abcde12345
Content-Disposition: form-data; name="signerId"
Content-Type: text/plain

{signerId}
--abcde12345
Content-Disposition: form-data; name="externalId"
Content-Type: text/plain

{externalId}
--abcde12345
Content-Disposition: form-data; name="name"
Content-Type: text/plain

{name}
--abcde12345
Content-Disposition: form-data; name="file"; filename="{fileName}"
Content-Type: application/pdf

{fileContent}
--abcde12345--

Content-Type: application/json
Content-Disposition: form-data; name="visualSignature"; filename="{visualSignatureFileName}"

{visualSignature}
--abcde12345--
Request Params
Attribute Type Description
size Number Document size in bytes.
signerId String Activation ID (Registration ID) from PowerAuth.
externalId String Custom unique ID identifying document in client’s systems.
name String Document name.
fileName String File name (including suffix), e.g. “attachment.pdf”.
fileContent String File content (binary data).
visualSignature String Optional parameter for visual signature definition as JSON. See PAdES Visible Signature.

Response

{
  "documentId": "String",
  "signerId": "String",
  "externalId": "String",
  "name": "String",
  "fileName": "String",
  "size": Number,
  "hash": "String",
}
Attribute Type Description
hash String SHA-256 summary of uploaded document. Hash has to be signed by user and used in Sign Document request.

Maximum file size limitations depends on server configuration (web/apps server, database, network) with max size around 50MB.

Document mime-type validation is performed.

Because the hash of the document (including signature metadata) is calculated at this step, the document cannot be updated later. For example, this affects the signature timestamp in the signed document, since the time of upload is used rather than the time when the document is actually signed (assembled).

put /documents/{documentId} Reject Document

Reject document and terminate signing process.

Request

{
  "status": "REJECTED"
}
Request Params
Attribute Type Description
documentId String Custom Unique ID identifying document in client’s systems.
status String Set status to REJECTED.

Response

{
  "documentId": "123abc",
  "name": "Document name",
  "fileName": "real_document_name.pdf",
  "size": 343425734,
  "hash": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
}

delete /documents/{documentId} Delete Document

Delete document, no matter if it’s only uploaded or signed document.

Request
Request Params
Attribute Type Description
documentId String Custom Unique ID identifying document in client’s systems.

Response

204 No Content

post /documents/{documentId}/signature Sign Document

Complete the signature with approved document hash.

Request

{
  "signature": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}
Request Params
Attribute Type Description
documentId String Custom Unique ID identifying document in client’s systems.
signature String Hash taken from Document Upload and signed with private key on mobile device.

Response

{
  "documentId": "123abc",
  "uri": "https://HOSTNAME/documents/{documentId}"
}

get /documents/{documentId}/file Download Document

Download document.

As you can see from the Accept-Ranges: bytes response header, we support optional Range request header to download content partially. In this case Content-Range header will be returned in the response (otherwise it will be omitted).

Request

Range: bytes=0-999
Request Params
Attribute Type Description
Range String Optional byte range.
documentId String Custom Unique ID identifying document in client’s systems.

Response

Accept-Ranges: bytes
Content-Length: 1000
Content-Range: bytes 0-999/98024
Content-Type: application/pdf

{fileContent}
Last updated on Oct 10, 2025 (12:40) Edit on Github Send Feedback
Search

develop

Signer Cloud