In order to use SignCloud API, every url must be composed as follows:
https://{signcloudhost}/api/{resource}
The {signcloudhost} changes according to the environment:
and {resource} is the name of the resource of our interest.
Example:
Example
A simple HTTP POST request made with curl.
1 | curl -H "Content-Type: application/json" -d @params.json -X POST https://{signcloudhost}/api/sign_rsa
The response of each api call is a JSON object with just 2 keys:
result | In case of success it is setted to True or contains some other values. Otherwise it is None |
error | In case of success its value is null. Otherwise it is a JSON object containing the error occured. This object has three keys: "msg" the error message, "code" the HTTP status code and "details" which can contain some extra info about the error. |
Examples
Here are listed some example responses returned by SignCloud
1 | {
2 | "result": "fp+6Ull5WbTRqbMtW5R80DVhX+Qcoev0OqiDcIwy3sJYtmBP2RtC6NgukFIALpbUR
3 | Dd3izbmjqx8GVF8/BO/vAaqIE5H+xzA553OCvBijXr4KV1W/VY70yEfS1u25xogjZjRj4tg9qEKu
4 | mvdA62qT5S0bgxpyL5ESBlrWY9oVaAiamIwfsw3VJQC6Lft/JJuE067oqd4DkvOy6RE1DMzk/imq
5 | ffCTfG+LG1fRV/JL3l7gMPO+mAcsTVeUOSC1hpZEDgahdQJmv3ec7wJazc+7eArulCmPQHsAJS4O
6 | 2AkXOb08/3XH5fH5b4B8vbLiWZG0SPT0adpfRI0euCXirDMBw==",
7 | "error": null
8 | }
1 | {
2 | "result": None,
3 | "error": {
4 | "msg": "Token locked",
5 | "code": 403,
6 | "details": ""
7 | }
8 | }
1 | {
2 | "result": null,
3 | "error": {
4 | "msg": "Missing parameter",
5 | "code": 412,
6 | "details": "'puk'"
7 | }
8 | }
1 | {
2 | "result": None,
3 | "error": {
4 | "msg": "Pin invalid",
5 | "code": 403,
6 | "details": ""
7 | }
8 | }
Below a list of HTTP codes, and their description, that can be returned by SignCloud
Code | Description |
---|---|
401 | Invalid Credentials |
403 | Token Not Found |
403 | Pin Invalid |
403 | Token Locked |
407 | Authentication Refused |
412 | Missing Parameter |
500 | Internal Server Error |
A postman collection is available as a support for a quick start.
SignCloud Postman collection download
Method | Endpoint | Action |
---|---|---|
POST | /verify_pin | Verify if the virtual token PIN is valid |
POST | /change_pin | Change a virtual token PIN |
POST | /unlock_pin | Unlock the PIN of a locked virtual token |
POST | /get_objects | Retrieve the public key and certificate of a specified SignCloud account |
POST | /token_info | Retrieve the token information of a specified SignCloud account |
Verifies if the specified PIN is valid.
Successful Response
Invalid Credentials
Invalid username
or pin
, User locked
Missing parameter in JSON object
Authentication refused (after 3 failed attempts)
{- "username": "string",
- "password": "string",
- "pin": "string"
}
{- "result": true,
- "error": null
}
Changes a token PIN.
Successful Response
Invalid password
Invalid username
or pin
, User locked
Missing parameter in JSON object
Authentication refused (after 3 failed attempts)
Internal Server Error
{- "username": "string",
- "password": "string",
- "pin": "string",
- "newpin": "string"
}
{- "result": true,
- "error": null
}
Unlocks the PIN of a locked token.
Successful Response
Invalid password
Invalid username
or puk
Missing parameter in JSON object
Authentication refused (after 3 failed attempts)
{- "username": "string",
- "password": "string",
- "newpin": "string",
- "puk": "string"
}
{- "result": true,
- "error": null
}
Retrieves the public key or the certificate of a specified SignCloud account.
JSON object that includes the user credentials for verification.
Successful Response
Invalid password
Invalid username
, User locked
Missing parameter in JSON object
Authentication refused (after 3 failed attempts)
Internal Server Error. identifier
or mechanism
not supported
{- "username": "string",
- "password": "string",
- "type": "null",
- "identifier": "DS0"
}
{- "result": [
- {
- "data": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArG9kf4t5lIRC96PfuhKGi0CmdCqUxYb3VstbwkvVdmSUBWm+OV1RzhSAR7BxP67e+5VsqKRN+PD273gA676xHIP1VDvrLmX3eOGqq6h3hpU+mQHQ8hzhONyv/uEDmF4ooJXh+zEjfGce/8K42VcMHmMrqj2GRQoyRmX02m95XiY8VMP7mqp5kmDHGQkWsDtJBKhXqMac4GbO8+yiw6MwR2xGhESxS09aaRjqp4bjvRMfFuNSZQL7/2jNufGbU+CBpnxrOoN+AP+vPOIhgXPlEC8Qk6POdKG9FHKLXVtz4DvPeHKyQ+MVbErjVyhK8fTOaR3BnZ+0bGHFf2AovRVfUwIDAQAB",
- "type": 3,
- "ckaid": "DS0",
- "label": "DS0_PublicKey"
}, - {
- "data": "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",
- "type": 4,
- "ckaid": "DS0",
- "label": "DS0_Certificate"
}
], - "error": null
}
Retrieves the token information of a specified SignCloud account. See description of succesful response for more details.
Successful Response
Invalid Credentials
{- "username": "string",
- "password": "string"
}
{- "result": {
- "puk_counter": 3,
- "label": "xxxxxx_Label",
- "qualified": true,
- "pin_counter": 3,
- "identifier": "xxxxxx",
- "webunlock": true
}, - "error": null
}
Method | Endpoint | Action |
---|---|---|
POST | /generate_otp | Generates an otp for the specified digital identity |
POST | /sign_rsa | Sign a base64 encoded buffer |
POST | /decrypt_rsa | Decrypt a base64 buffer |
Generates an otp for the specified digital identity.
⚠This method is only required and available for specific digital identities
Successful Response
{- "username": "string",
- "password": "string",
- "uses": 0
}
{- "result": {
- "identifier": "",
- "additional_data": {
- "max_uses": 10000,
- "qualified": true,
- "number": "",
- "webunlock": true
}
}, - "error": null
}
Signs a base64 encoded buffer.
JSON object that includes the user credentials for verification.
Successful Response
Invalid password
Invalid username
or pin
, User locked
Missing parameter in JSON object
Authentication refused (after 3 failed attempts)
Internal Server Error. Wrong identifier
or mechanism
or billing_username
or billing_password
{- "username": "string",
- "password": "string",
- "pin": "string",
- "identifier": "DS0",
- "mechanism": "string",
- "plaintext": "string",
- "billing_username": "string",
- "billing_password": "string",
- "otp": "string"
}
{- "result": "iaJp+O8CxSOPlPL4Eg4KBnlXDG+6g16wgp4ihVLIu3tJDIWFUFUHNgF/8+R1x3TJg4dCpKk6h3Tf+PapnJjGBgxnLeIA5nvdvKFu99Zlm0mS0Y6yjy6wMCEocWFtV+UBVpgXeDHae3XuiSHFu8c9TM7zdlnfmPRkZNHlb+HgafczuMAOfVsPepYsI4qlFIjS76v/6IczeGHV/aeSOa24jyNQsuVgBmbhHqqB8XQS9hHf+rQhvAgFv1o35HRgVDoNr93lkTflT88cjY+ip8ndc2QyY2nuuZmE4OR0ElGUV+9h+6/HMpl0hkHTX/NGRSdipHnZ93bNAahRRVK4okQLRQ==",
- "error": null
}
Decrypts a base64 buffer.
JSON object that includes the user credentials for verification.
Successful Response
Invalid password
User locked or Invalid username
or pin
Authentication refused (after 3 failed attempts)
Internal Server Error
{- "username": "string",
- "password": "string",
- "pin": "string",
- "identifier": "DS0",
- "ciphertext": "string"
}
{- "result": "Decrypted output",
- "error": null
}