Uanataca RA API allows the generation and distribution of digital certificates, either by integrating the issuance and management into a business application.
The Registration Authority is composed of people and processes, with the main function of identifying applicants of digital certificates and sending verified data for the issuance of the certificate.
Digital certificates are created and used as part of a life-cycle that includes three fundamental stages:
The complete flow is explained in the next section Flow chart
As part of the paperless procedure, every Request has its own digital contract that has to be electronically signed by the RA Operator (in charge of approving the Request) and the certificate subscriber, each one with their respective digital certificates.
List of entities and names used to describe UANATACA's services
Certification Authority (CA)
The CA is the issuer of the certificates requested by the Registration Authority.
Registration Authority (RA)
The RA manages the entire life-cycle of digital identities, from the certificate issuance to suspension, reactivation, renewal and revocation of the PKI credentials. Reuests are generated and verified by a Registration Authority Officer.
Registration Authority Officer (RAO)
The RAO follows strict guidelines and policies defined to ensure the trust of the CA. RAO is responsible for managing the requests for digital certificates and verifying the content of the requests as well as identifying people requesting them.
API User
The Account having access to the APIs provided by the system. It is generally used for a server to server interaction.
Certificate Request (Request)
It is a request to issue a new certificate. A request can be associated with only one RA and has a status attribute to monitor the progress of the application:
CREATED: The request has been created and associated to an RA, but the content of the request has not been validated yet. In this state, data can also be inconsistent, the system will not throw an error. The content of the request can be edited at any moment to make it valid.
ENROLLREADY: The certificates are ready to be issued. The request arrives at this stage, if it has been approved and signed by a RAO, who is part of the RA in charge of the request.
ISSUED: The certificate is issued by the user's self-service page on the platform. The user must first set a PIN code or a password regarding the secure element.
RENEWED: The certificate is renewed by the user's self-service page on the platform.
CANCELLED: The request is cancelled and the digital certificate can not be issued.
Scratchcard
It is a virtual scratch card containing the secret codes of the user.
The card contains:
It is important to notice that a scratchcard can be used only once. Every request must be associated with a different scratchcard.
The common digital certificate generation process involves the following steps:
1) CREATION OF A REQUEST
2) UPLOAD DOCUMENTS
3) REQUEST APPROVAL
STEP 1: CREATION OF A REQUEST
API Reference: Get First Unused Scratchcard
This call simply requires a Registration Authority (RA) id number. Scratchcards must be available for this RA for successful response.
curl -i -X GET https://api.uanataca.com/api/v1/scratchcards/get_first_unused/ \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
"ra": "121"
}'
The response is a JSON object containing the single-use Scratchcard associated data. The scratchcard number sn must be added to the Create Request call.
{
"pk": 1193,
"sn": "1256948",
"secrets": "{\"erc\": \"6292998123\", \"enrollment_code\": \"_,463vt:\", \"pin\": \"08695572\", \"puk\": \"52351291\"}",
"registration_authority": 121
}
API reference: Create Request
This call must include enough information to identify the requester user. The full description of the arguments accepted by this endpoint can be found in the API call detailed documentation.
curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
"profile": "PFnubeAFCiudadano",
"scratchcard": "5053311",
"secure_element": "2",
"registration_authority": "116",
"country_name": "ES",
"serial_number": "12345678A",
"id_document_country": "ES",
"id_document_type": "IDC",
"given_name": "Name",
"surname_1": "Surname1",
"surname_2" "Surname2"
"email": "mail@domain.com",
"mobile_phone_number": "+34611223344",
"paperless_mode": 1
}'
The response is a JSON containing info from the created request. One of the most important parameters from this JSON is the pk which represents the request unique identifier and is used for every operation related to this request.
{
"pk": 11223,
"given_name": "Name",
"surname_1": "Surname1",
"surname_2": "Surname2",
"sex": null,
"id_document_type": "IDC",
"id_document_country": "ES",
"serial_number": "12345678A",
"country_name": "ES",
"citizenship": null,
"residence": null,
"organization_email": null,
"email": "mail@domain.com",
"title": null,
"organization_name": null,
"organizational_unit_1": null,
...
}
STEP 2: UPLOAD DOCUMENTS
API reference: Upload Document
The created request needs documents, so we can query with an HTTP POST request to upload the files.
The required documents for every request are:
document_front : The photo of the front side of the requester ID card
document_rear : The photo of the rear side of the requester ID card
extra_document : If necessary, it is possibile to upload extra documents that represents additional requester information
Additionally a selfie of the requester showing the ID card under the chin can be uploaded as an evidence under the type document_owner.
Note that this endpoint has to be queried for every document type that the Request needs.
curl -i -X POST 'https://api.uanataca.com/api/v1/requests/11223/pl_upload_document/' \
--cert 'cer.pem' --key 'key.pem'
-H 'Content-Type: multipart/form-data' \
-F document=@/idc_front.jpg \
-F type=document_front
The response contains the uploaded document unique identifier associated to the request.
{
"pk": 11314,
"type": "document_front"
}
STEP 3: REQUEST APPROVAL
A Registration Authority Officer must first validate the request data and documentation. If the information is correct, the RAO will approve the request by signing the receipt and contract with his or her own cloud certificate.
API Reference: Generate RAO Declaration
curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/generates_tbs_receipt/ \
-H 'Content-Type: application/json' \
-d '{
"rao": "1400",
"type": "APPROVE"
}'
The following JSON object contains the receipt:
{
"serial_number": "3ef3696d2939241d",
"receipt": "El operador RAO_Name RAO_Surname1 con número de identificación 12345678P\r\nactuando en calidad de operador autorizado de registro del prestador de servicios\r\n
de confianza UANATACA, S.A. con NIF A66721499, (UANATACA en lo sucesivo)\r\n\r\nDECLARA\r\n\r\nQue previa verificación de acuerdo a la Declaración de Prácticas de
UANATACA\r\npublicadas en www.uanataca.com, la información detallada a continuación es\r\ncorrecta y será incluida (donde aplicable) en la solicitud de
certificados\r\ncualificados:\r\n\r\n- Datos de Identificación de la solicitud de certificados: 36893\r\n- Nombre y Apellidos del Firmante: Name Surname1 Surname2\r\n- DNI/
NIE/PASAPORTE del Firmante: 11111111B\r\n- Dirección de correo electrónico del Firmante: mail@domain.com\r\n\r\n\r\n18/03/
2021\r\n\r\n\r\n\r\n--------------------------------------------------------------------\r\nFdo. User Admin\r\nOperador autorizado de registro"
}
Similarly, it is necessary to retrieve the service contract and present it to the RAO before approval.
API Reference: Generate Contract (use type: contract in body)
curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/pl_get_document/ \
-H 'Content-Type: application/json' \
-d '{
"type": "contract"
"rao_id": "1400"
}'
The response consists in a JSON structure containing the contract in Base64 format.
[
{
"document": "JVBERi0xLjQKJZOMi54gUmVwb3J0TGFiIEdlbmVyYXRlZCBQREYgZG9jdW1lbnQgaHR0cDovL3d3\ndy5yZXBvcnRsYWIuY29tCjEgMCBvYmoKPDwKL0YxIDIgMCBSCj4 (...)\n",
"type": "contract"
}
]
API reference: Approve Request
In order to approve a Request, this must be in the status of CREATED and must have at least the required documents (document_front and document_rear).
curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
"username": "1000279",
"password": "3DPTm:N4",
"pin": "23bYQq9a",
"rao_id": 123
}'