Using Local signing - API - Transaction (text) signing using PhenixID OneTouch
Overview
To use the API, two methods must be called. The first API method call is to trigger the signing. This will return a transaction ID value. The second API method call will poll the status of the signing. The API client must poll until a status=OK or an error is returned.
Prerequisites
- PhenixID Signing Service API for PhenixID OneTouch configured
- If PhenixID Signing Service Local Signing API is protected with client certificate authentication: Client certificate (p12)
- If PhenixID Signing Service Local Signing API is protected with basic authentication: Username and password
Trigger signing - data to be fetched before api call
To trigger signing, the api client must fetch these values before calling the api:
- UserID
- Data to be signed
Trigger signing - api call
Request
Method: HTTP PUT
Endpoint: /api/authentication/onetouch/assign
Headers:
| Name | Value |
Mandatory | Comment |
|---|---|---|---|
| Content-Type | application/json | Yes | |
| tenant | t1 | Yes | Value must be given to you by PhenixID Signing Service admin, it might differ depending on the environment. |
| Authorization | <basic_auth_value> | No | If applicable, username and password must be given to you by PhenixID Signing Service admin. |
Body:
The body must contains a json structure.
{
"assigned_to":"<user_id>",
"form":
{
"style":"style1",
"controls":
[{
"id":"label_1",
"type":"label",
"value":"<Text_to_be_signed>",
"style":"style1"
},
{
"id":"button_1",
"type":"button",
"value":"SIGN",
"action":"CONFIRM"
},
{
"id":"button_2",
"type":"button",
"value":"CANCEL",
"action":"REJECT"
}],
"styles":
[{
"id":"styleid1",
"text_color":"#ffff00ff",
"background_color":"#ffffffff",
"text_alignment":"center",
"text_bold":"true",
"text_italic":"false",
"text_size":"medium",
"vertical_alignment":"center"
}]
},
"signatures":
[{
"id":"id1",
"algorithm":"Sha256WithRsa",
"data":"<Text_to_be_signed>",
"content_type":"text/plain",
"content_encoding":"none"
}]
}Json properties to be populated by the api client:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| assigned_to | <user id> | Yes | The userID must be set here. |
| form->controls->id=label1->value | <Data to be signed> | Yes | The text to be signed must be set here. |
| signatures->data | <Data to be signed> |
Yes | The text to be signed must be set here. |
Example request (Please note that authorization data is not included in this example).
PUT /api/authentication/onetouch/assign HTTP/1.1
Host: example.org
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "assigned_to":"andbjo", "form": { "style":"style1", "controls": [{ "id":"label_1", "type":"label", "value":"Sign this please.", "style":"style1" }, { "id":"button_1", "type":"button", "value":"SIGN", "action":"CONFIRM" }, { "id":"button_2", "type":"button", "value":"CANCEL", "action":"REJECT" }], "styles": [{ "id":"styleid1", "text_color":"#ffff00ff", "background_color":"#ffffffff", "text_alignment":"center", "text_bold":"true", "text_italic":"false", "text_size":"medium", "vertical_alignment":"center" }] }, "signatures": [{ "id":"id1", "algorithm":"Sha256WithRsa", "data":"Sign this please.", "content_type":"text/plain", "content_encoding":"none" }] }Response
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 45
{
"id": "dff4ad59-0c9d-4846-a53b-5c6848cceec3"
}Collect signature - use id
The API client must fetch the id returned by the Trigger sign call.
The API client must call the Collect Signature API method periodically until it returns a status CONFIRMED or an error message.
Collect signature - api call
Request
Method: HTTP PUT
Endpoint: /api/authentication/onetouch/check
Headers:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| Content-Type | application/json | Yes | |
| tenant | t1 | Yes | This value must be given to you by the PhenixID Signing Service admin. |
| Authorization | <basic_auth_value> | No | Basic authentication username and password must be given to you by PhenixID Signing Service admin. |
Body:
The body must contains a json structure.
{"id":"..."} Json structure properties:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| id | <Value_returned_from_trigger_sign> | Yes |
Example request (Please note that authorization data is not included in this example).
PUT /api/authentication/onetouch/check HTTP/1.1
Host: example.org
Content-Type: application/json
tenant: t1
pipeID: bankidcollect
Cache-Control: no-cache{ "id": "dff4ad59-0c9d-4846-a53b-5c6848cceec3" }Response
Response
The response body JSON structure properties:
| Name | Possible values | Comment |
|---|---|---|
| status | CONFIRMED PENDING REJECTED |
PENDING -> Continue to poll Other status -> Stop polling |
| signatures->value | The signature. Only available if status=CONFIRMED. | |
| signcertificate | The X509 certificate that was used to sign the data. |
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 390010
{
"assigned_to" : "andbjo",
"form" : {
"style" : "style1",
"controls" : [ {
"id" : "label_1",
"type" : "label",
"value" : "Sign this please.",
"style" : "style1"
}, {
"id" : "button_1",
"type" : "button",
"value" : "SIGN",
"action" : "CONFIRM"
}, {
"id" : "button_2",
"type" : "button",
"value" : "CANCEL",
"action" : "REJECT"
} ],
"styles" : [ {
"id" : "styleid1",
"text_color" : "#ffff00ff",
"background_color" : "#ffffffff",
"text_alignment" : "center",
"text_bold" : "true",
"text_italic" : "false",
"text_size" : "medium",
"vertical_alignment" : "center"
} ]
},
"signatures" : [ {
"id" : "id1",
"data" : "Sign this please.",
"value" : "hHgmpWD0VUrZf4E1N8i2ATO+yULX3uWEnRTeZ4cavrOlaIssIf2iKoV4DFYrK46GA/inHGXH1jC+b1YZ3bWsh7xJzMsFDYFX5lXxix8QQIBL5h6HsXa/MIp9wIz7HZQpUbjVFDX9to5Pddi4QgTfhEAEF6p7kkIt40TcrOwfpO5i021SmMLTS784PQwbI2lzjy7Xul4yluVqwlIJ28XqtqCuD9adB/lP9teTmn+jttIrlyCEpeEqyZ7WqodG3vNrd5eBXH2IH6W86xqeuFhaHiS+0+5qBo1ltkd1bBaIdtQGwxM8P8r9eXrfoDkdRb0ArDV4XOTKo9nmZXOll0AWSw==",
"content_encoding" : "none",
"algorithm" : "Sha256WithRsa",
"content_type" : "text/plain"
}, {
"id" : "form",
"data" : "pid=558b199a-c1c2-4a1c-89ca-3409378e87df&aid=dff4ad59-0c9d-4846-a53b-5c6848cceec3&ts=1513848176073&label_1=Sign%20this%20please.&button_1=SIGN&id1=Sign%20this%20please.",
"value" : "rl5V4D/ud7i6M299nejk5me31bXPcH7rBQVY/3oEe7SxAJhxFTyT7X5OFrjhcCZkEClZAeMgLR03coDDrjl8SbmoI0AlxIuOuPNng/mNcuNQZu32JW0dKtFr4BMU9Kmv7Pnc7iuCEdp59EaESHx2z1ZO+Nz0GgO/Lce7oxWjVjem3PxidUMHhkymZNFuO+XFBCHE7/jcLHH0SU6SbunZ0yFxZXD/X1MlBUKovn2NnqunjDYY+Wv2PNfCxbgnlIJa57ifFf2w4Io1tIOXB5h5ClrG5XmzQzXGXcF7PtUEwUKtlT2fzNmBNiNyTAvQPp8MjT/6iMaiOgDDRlIH/9qjdQ==",
"content_encoding" : "none",
"algorithm" : "Sha256WithRSA",
"content_type" : "text/plain"
} ],
"expires" : "2017-12-21T09:26:32.452Z",
"status" : "CONFIRMED",
"id" : "dff4ad59-0c9d-4846-a53b-5c6848cceec3",
"created" : "2017-12-21T09:21:32.468Z",
"modified" : "2017-12-21T09:23:06.405Z",
"signcertificate" : "\rMIIC9TCCAd2gAwIBAgIGAWA2UtmhMA0GCSqGSIb3DQEBCwUAMCAxHjAcBgNVBAMM\rFVBoZW5peElEIE9uZSBUb3VjaCBDQTAeFw0xNzEyMDgxMzMxMjdaFw0xODEyMDgx\rMzMxMjdaMBExDzANBgNVBAMMBmFuZGJqbzCCASIwDQYJKoZIhvcNAQEBBQADggEP\rADCCAQoCggEBAMh7YHw4UXWMtGZbxHIn4YeKGLd3jQhB+aAJIxFa2oRlUmeY7cjF\rlZQa7zErLaWc2AmBWYbDw3W1/ZQed1uINBgsMbk8SiDTXeGG68ZvRgUy/Yo+AgGt\rdx+C4A/91t7vj4XKIti43ONg9CJh6p+TkmwYzgCMBnrHW62YdXLB8fFqUei7iLTf\rGqEGeBnONQUH2y0Q5ZtFer8pdqPqiuFqqrMfztEpmLdWFtm2f7x2mnRl35IOoiQj\rF39/Qbx/QXxc8WoHO8HQcCvyha5U6+QAy/AMZexJHixKdtUGYFvcsHpffYHfeFNA\r//iLXVt+Jk+VmB5tJgJcBtIYDTqsTQQmDTUCAwEAAaNEMEIwDgYDVR0PAQH/BAQD\rAgbAMDAGCCsGAQUFBwEBBCQwIjAgBggrBgEFBQcwAYYUe3tyZXF1ZXN0Lm9jc3Bf\rdXJsfX0wDQYJKoZIhvcNAQELBQADggEBAIV48rLK/UWnpPzRIeRfNKFAcMjKeW30\rWeMD98qP7qdsibJPre8jXqVoUUliQUyxgE6tRzg72jAF2uz3fuXr+/mqs751IExU\reYosqVeETV0CFNYWNxdbx2yXj3MqYyCNostDvD9QUNpgVdZ2uOP5aI3UdzR3DzKJ\rGoXXI4P1vLEfDHXl5t39yV0BxHG4svYpkiV9odxdTqezn8sZNiidM227iClvsnyR\r7cNHDv6n67mlFBKQXffXWhAc4brIPVQWHcsZjvx/OV7mzXOke8u++2kMu85lNBoN\r86CEqMcWPNJabMJoMh9KhVUX8yceqNtWsTl6pD1G2YFlg7mxL40MgYY=\r\r",
"token_ref" : "558b199a-c1c2-4a1c-89ca-3409378e87df"
}Common errors
Common errors will result in a HTTP Status 500. Check server log file to trace error.