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.