Signer Cloud API
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 |
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--
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). |
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}