Using One-Shot Signature

This section section presents the workflow for a simple use case of the One-Shot Signature service with a step-by-step description of the API calls required to allow a user to digitally sign a document provided by the client application.

You can follow the example using the One-Shot Optimizer virtual machine configured for the test environment. You can find the instructions to set up the virtual machine in the configuration page.

Before we begin, let's recap the objects and entities involved in the operation:

Registration Authority Officer (RAO) is an agent authorized by a Registration Authority to enroll new accounts into a private key infrastructure system. For the One-Shot Signature service, this means the agent in charge of collecting all identifying information for each user and creating new signature requests.

Token One-Shot Signature uses tokens to identify the RAO who creates each signature request. While the use of tokens is entirely optional, it is often convenient to create and use a token for a RAO instead of introducing the full credentials every time that they are required.

Document A PDF file to be signed.

One-Time Password (OTP) a secret code sent by SMS directly to your users so that they can confirm their identity and complete the digital signature.

Workflow

The basic digital signature process involves the following steps:


Retrieve an existing token for the RAO

The test One-Shot Optimizer virtual machine is pre-configured with a RAO account ready to be used within the test environment. This account has an associated token, that can be used to identify the RAO in API calls. We can list existing tokens with the /api/v1/tokens API endpoint.

Assuming that https://oneshot.demo.uanataca.com is the URL for the One-Shot Optimizer virtual machine, we can access the endpoint with:

curl -X GET https://oneshot.demo.uanataca.com/api/v1/tokens

On the clean machine, this should return a single token:


                {
                    "status": "200 OK",
                    "details": {
                        "791ef6ff519b41cfa2f311e6cd144586": {
                            "username": "9900123",
                            "password": true,
                            "pin": true
                        }
                    }
                }
            

This output tells us that a single token "791ef6ff519b41cfa2f311e6cd144586" exists. This token is associated to the RAO account with id "9900123" and can be used in place of the password and pin.

To use tokens in a production environment, you will need to create them first with the corresponding API call.

Tokens can also be generated without providing all credentials. In that case, the missing credentials (pin or password) have to be provided as additional arguments every time the token is used.


Create a new Digital Signature Request

Within the One-Shot Signature Service, all data pertaining to a given digital signature is collected within a Digital Signature Request. This includes both the identifying information of the signing user, which is provided when you create the signature request, and the document or documents to be signed, which we will upload later.

We can crete a new signature request with a POST call to the api/v1/request API endpoint. This call must include enough information to identify both the signing user and the RAO initiating the request. The full description of the arguments accepted by this endpoint can be found in the detailed documentation, but for now it is enough to include at least the following:


                curl --location --request POST 'https://oneshot.demo.uanataca.com/api/v1/request' \
                     --form 'token=791ef6ff519b41cfa2f311e6cd144586' \
                     --form 'profile=PFnubeAFCiudadano' \
                     --form 'given_name=name_of_the_user' \
                     --form 'surname_1=surname_of_the_user' \
                     --form 'email=user-example@domain.com' \
                     --form 'mobile_phone_number=+393391234567' \
                     --form 'document_front=@document_front.png' \
                     --form 'document_rear=@document_rear.png' \
                     --form 'document_owner=@document_owner.png'
            

where token is the token representing the RAO credentials obtained in the previous step.

Note that here we are providing images of the user's identification document. These may not be required in production if your Registration Authority allows enrollment without documents.

If the signature request is completed successfully, we will get the unique identifier assigned to it:


                {
                    "status": "201 Created",
                    "details": 1464
                }
            

The request code will be used to identify this digital signature request in subsequent calls.


Upload a document

After creating the digital signature request, we can associate to it all documents that should be signed by the user. For each document, we make a multipart/form-data HTTP POST request with the PDF document to upload.

curl -F "file=@doc.pdf" -X POST https://oneshot.demo.uanataca.com/api/v1/document/1464

Note that the number at the end of the call is the request id we obtained in the previous step.

If the upload is successful, the response will contain the identifier assigned to the document:


                {
                    "status": "200 OK",
                    "details": "712c29ac-a2dc-4530-8c67-d0f227d8294b"
                }
            

Generate an OTP

Once the documents to be signed are ready, we need to generate a secure One time password (OTP) that will allow the user to sign them. The OTP is generated by calling the otp endpoint and the resulting OTP is sent as an SMS message directly to the phone number we provided when creating the signature request.

When calling the OTP endpoint, provide the request identifier returned by the request endpoint:

curl -X POST https://oneshot.demo.uanataca.com/api/v1/otp/1464

A successful call will look like this:


                {
                    "status": "200 OK",
                    "details": "OTP generated"
                }
            

With this call, an SMS with the secret is sent to the mobile phone number associated to the signature request.


Sign the document

In this step we are going to finalize the creation of the signature certificate and sign all documents previously uploaded for the signature request.

Call the sign endpoint with the request id and json parameters containing the OTP:

params.json:

                {
                    "secret": "000000",
                }
            
curl -d @params.json -H "Content-Type: application/json -X POST https://oneshot.demo.uanataca.com/api/v1/sign/1464

A successful call will result in the following response:


                {
                    "status": "200 OK",
                    "details": "Documents correctly signed"
                }
            

Retrieve signed document

The only remaining step is getting the signed document.

To do this, query with an HTTP GET request the endpoint /api/v1/document/{pk}/{type}/{uid}, where {pk} is the Request's unique identifier, {type} is the type of the document (it can be "original" for the uploaded document or "signed" for the digitally-signed version) and {uid} is the unique id string assigned to the document.

curl -X GET https://oneshot.demo.uanataca.com/api/v1/document/1464/signed/712c29ac-a2dc-4530-8c67-d0f227d8294b

The response by the server will be the document in binary format:


                %PDF
                ...
            

Note that you can call the "original" variant of the endpoint at any point after uploading the document, while the "signed" version is only available after calling the sign endpoint for the request.