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.
Uanataca expose its API on urls composed as follows:
https://{uanatacahost}/api/{version}/{resource}/⚠ Make sure the URL always ends with a forward slash ("/")
uanatacahost
The host changes according to the environment:
⚠ In test environment you need to trust the certificate Bit4idCA.crt
version
It is the api version (currently v1)
resource
It is the name of the resource of our interest.
Each resource can also have path parameters and sub-resources that are defined in the API Reference below:
This is an example of endpoint exposed by Uanataca:
https://api.uanataca.com/api/v1/requests/123/cloud_enroll/The API authentication is perfomed providing to the server the certificate and the key of an enabled API User.
This is an example HTTP POST request perfomed with cURL:
1 | curl --key key.pem --cert cert.pem -H "Content-Type: application/json" -d @params.json -X POST https://api.uanataca.com/api/v1/requests/and a Python with requests package example:
1 | import requests
2 | requests.get(
3 | 'https://api.uanataca.com/api/v1/scratchcards/',
4 | cert = ('/path/to/cert.pem', '/path/to/key.pem')
5 | )Every response body returned by Uanataca is JSON object.
If the response is successful, the content of the JSON depends on the API queried.
Instead, the error response is always composed of these keys:
| Key | Description |
|---|---|
| error | A string that describe the error occured |
| code | The HTTP response code related. See table descriptions |
| id | The unique identifier of the error generated by Uanataca |
In the API Reference are described the response structures for each API call.
A successful response:
1 | [
2 | {
3 | "data": "MIIHyTCCBbGgAwIBAgIIcO...",
4 | "profile": "PFnubeAF",
5 | "subject": "CN=RAO COFTenerife API, 2.5.4.5=TINIT-TSTAPI74S23C129Y, 2.5.4.42=RAO, 2.5.4.4=API, C=ES",
6 | "issuer": "2.5.4.97=VATES-A66721499, CN=UANATACA CA1 2016, OU=AC-UANATACA, O=UANATACA S.A., L=Barcelona (see current address at www.uanataca.com/address), C=ES",
7 | "valid_from": "2018-10-16T16:41:00",
8 | "valid_to": "2020-10-15T16:41:00",
9 | "serial_number": "70e07489bfccd478",
10| "status": 0,
11| "pk": 1980,
12| "revokation_reason": null,
13| "type": "FIRSTISSUE"
14| }
15| ]An error response:
1 | {
2 | "code": "500",
3 | "id": "8e782cdcdb600a90",
4 | "error": "Invalid ScratchCard"
5 | }| Code | Description |
|---|---|
| 200 | Everything went OK. The server elaborated correctly the request and returned the response to the client. |
| 201 | The object is successfully Created with the parameters sent by the client. |
| 202 | The request sent by the client has been Accepted and is under process. |
| 204 | No Content. The operation was successful but no content is provided in the response body. |
| 400 | Bad Request. The parameters sent, are not well formatted or are missing. |
| 401 | Unauthorized. The user used for making the request is not authorized to consume that resource. |
| 403 | Forbidden.The user used for making the request has no permissions to do it. |
| 404 | The resource requested is Not Found. |
| 405 | Method not allowed. The endpoint called has not the method specified. |
| 412 | Precondition Failed. The operation has some requirements that are not satisfied. For example if a Request is in a wrong state for the operation requested. |
| 429 | Too Many Requests. |
| 500 | Internal Server Error. An error occured during the elaboration of the request. |
| 502 | Bad Gateway. |
| 503 | Service Unavailable. |
Some endpoints works with the mechanism of pagination.
This means that when an API returns the content requested, the JSON is composed with the keys:
| Key | Description |
|---|---|
| count | Represents the number of object found |
| next | Represents the url of the next page (it is null if there are no more pages) |
| previous | Represents the url of the previous page (it is null if there are no more pages) |
| result | Contains a list of objects found |
Every page contains at most 10 objects.
Examples
Here are display a couple of JSON returned by Uanataca.
A list of Scratchcards:
1 | {
2 | "count": 40,
3 | "next": "https://api.uanataca.com/api/v1/scratchcards/?page=2®istration_authority=8",
4 | "previous": null,
5 | "results": [
6 | {
7 | "pk": 801,
8 | "sn": "2000100",
9 | ...
10| },
11| {
12| "pk": 800,
13| "sn": "2000099",
14| ...
15| },
16| ...
17| ]
18| }A list of Requests:
1 | {
2 | "count": 643,
3 | "next": "https://api.uanataca.com/api/v1/requests/?page=2",
4 | "previous": null,
5 | "results": [
6 | {
7 | "pk": 788,
8 | ...
9 | },
10| {
11| "pk": 789,
12| ...
13| },
14| ....
15| ]
16| }This section section presents the workflow for a common digital certificate generation with a step-by-step description of the API calls required.
The common digital certificate generation process involves the following steps:
STEP 1: Create a Request
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.
1 | curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
2 | -H 'Content-Type: application/json' \
3 | --cert 'cer.pem' --key 'key.pem'
4 | -d '{
5 | "profile": "PFnubeAFCiudadano",
6 | "scratchcard": "5053311",
7 | "secure_element": "2",
8 | "registration_authority": "116",
9 | "country_name": "ES",
10| "serial_number": "12345678A",
11| "id_document_country": "ES",
12| "id_document_type": "IDC",
13| "given_name": "Name",
14| "surname_1": "Surname1",
15| "surname_2" "Surname2"
16| "email": "mail@domain.com",
17| "mobile_phone_number": "+34611223344",
18| "paperless_mode": 1
19| }'The return response is the a JSON containing the info of the Request just created. 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.
1 | {
2 | "pk": 11223,
3 | "given_name": "Name",
4 | "surname_1": "Surname1",
5 | "surname_2": "Surname2",
6 | "sex": null,
7 | "id_document_type": "IDC",
8 | "id_document_country": "ES",
9 | "serial_number": "12345678A",
10| "country_name": "ES",
11| "citizenship": null,
12| "residence": null,
13| "organization_email": null,
14| "email": "mail@domain.com",
15| "title": null,
16| "organization_name": null,
17| "organizational_unit_1": null,
18| ...
19| }STEP 2: Upload documents
API reference: Upload document
The Request created 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.
1 | curl -i -X POST 'https://api.uanataca.com/api/v1/requests/11223/pl_upload_document/' \
2 | --cert 'cer.pem' --key 'key.pem'
3 | -H 'Content-Type: multipart/form-data' \
4 | -F document=@/idc_front.jpg \
5 | -F type=document_frontThe return response contains the uploaded document unique identifier associated to the request.
1 | {
2 | "pk": 11314,
3 | "type": "document_front"
4 | }STEP 3: Approve Request
API reference: Approve a request
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.
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).
1 | curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
2 | -H 'Content-Type: application/json' \
3 | --cert 'cer.pem' --key 'key.pem'
4 | -d '{
5 | {
6 | "username": "1000279",
7 | "password": "3DPTm:N4",
8 | "pin": "23bYQq9a",
9 | "rao_id": 123
10| }STEP 4: Enrollment
There are different endpoints to enroll a Request, depending on the secure element choosen.
For all requests is required to send an otp code to the requester. Software and cloud certificates use the same call to send the otp code, while cloud-qscd certificates use another.
API reference: Send OTP code for software and cloud
API reference: Send OTP code for cloud-QSCD
Software
API reference: Software enrollment
For the Software enrollemnt the parameters required are the secret OTP code send to the requester and the p12password set by the requester to import the generated p12:
1 | {
2 | "secret": "000000",
3 | "p12password": "password12"
4 | }At the end of the enrollment the server replies with the P12 generated in PEM format.
Cloud
API reference: Cloud enrollment
For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:
1 | {
2 | "secret": "000000",
3 | "pin": "pincode12"
4 | }At the end of the enrollment the server replies with a JSON containing all requesta data.
Cloud-QSCD
API reference: Cloud-QSCD enrollment
For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:
1 | {
2 | "secret": "000000",
3 | "pin": "pincode12"
4 | }At the end of the enrollment the server replies with a JSON containing all requesta data.