Using Local signing - API - Transaction (text) signing using NetID Access
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=COMPLETE or an error is returned.
Prerequisites
- PhenixID Signing Service Transaction Signing API configured
- NetID Access client
- NetID Access certificate enrolled
- If PhenixID Signing Service Transaction Signing API is protected with client certificate authentication: Client certificate (p12)
- If PhenixID Signing Service Transaction 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:
- UserID (UserID, matching the Subject-serialnumber of the certificate enrolled)
- Data to be signed that should be displayed to the user
For more information about signatures, formats etc, please view SecMaker NetID Access documentation.
Trigger signing - api call
Request
Method: HTTP PUT
Endpoint: /api/sign/NIASStartSign
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.
{
"userid":"..",
"userVisibleData":".."
} Json structure properties:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| userid | <user identification> | Yes | UserID. Must match the value of the subject-serial of the certificate enrolled. |
|
userVisibleData |
<Data to be signed that will be displayed to the user in the NetID Access client> | Yes | Please view Secmaker NetID Access documentation for recommendations. |
Example request (Please note that authorization data is not included in this example).
PUT /api/sign/NIASStartSign HTTP/1.1
Host: example.org
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{
"userid":"191212121212",
"userVisibleData": "This is the data to be signed that will be displayed in the NIAS client"
}Response
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
"transactionID":"829b3b56-5a0a-449f-8dc8-50e6772c076f"
}Collect signature - use transactionID
The API client must fetch the transactionID returned by the Trigger sign call.
The API client must call the Collect Signature API method periodically until it returns a status OK or an error message.
Collect signature - api call
Request
Method: HTTP PUT
Endpoint: /api/sign/niascollect
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.
{"transactionID":"..."} Json structure properties:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| transactionID | <Value_returned_from_trigger_sign> | Yes |
Example request (Please note that authorization data is not included in this example).
PUT /api/sign/niascollect HTTP/1.1
Host: example.org
Content-Type: application/json
tenant: t1
Cache-Control: no-cache{"transactionID":"829b3b56-5a0a-449f-8dc8-50e6772c076f"}Response
Response
The response body JSON structure properties:
| Name | Possible values | Comment |
|---|---|---|
| status | COMPLETE OUTSTANDING_TRANSACTION USER_SIGN USER_CANCEL SIGN_VALIDATION_FAILED INTERNAL_ERROR UNKNOWN_USER |
OUTSTANDING_TRANSACTION or USER_SIGN -> Continue to poll Other status -> Stop polling |
| signature | The signature data. Only available if status=COMPLETE. | |
| ocspResponse | The OCSP Response. Only available if status=COMPLETE. | |
| name | Full name of certificate holder. Only available if status=COMPLETE. | |
| givenName | Given name (first name) of certificate holder. Only available if status=COMPLETE. | |
| surName | Last name of certificate holder. Only available if status=COMPLETE. |
|
| message | Error message. Only available if status=INTERNAL_ERROR. | |
| details | Detailed error message. Only available if status=INTERNAL_ERROR. |
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3295
{
"surName" : "Berg",
"signature" : "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",
"ocspResponse" : "",
"givenName" : "Anders",
"name" : "Anders Berg",
"status" : "COMPLETE"
}Common errors
Common errors will result in a HTTP Status 500 with a body containing the error message:
{”message”:”<error explained>”}