...
...
...
...
...
ACCESS URL TO WEB SERVICES
| Code Block |
|---|
<endpoint>/<operation>/ |
...
...
...
...
...
...
...
...
...
You
...
...
...
url = <endpoint>/individuals/search (POST)...
...
...
...
...
...
...
...
Index (GET)
| Code Block |
|---|
url = <endpoint>/individuals/ (GET) |
...
...
...
...
...
...
...
...
...
...
USE: Individuals creation
Params:
...
...
...
...
...
...
...
...
...
...
...
...
...
| Code Block |
|---|
individual[first_name]=Ruben&
individual[last_name]=Garcia&
individual[national_number]=20987390&
individual[national_number_type]=DNI&
individual[email]=rhgarcia%40example.com |
...
...
...
...
...
...
| Code Block |
|---|
url = <endpoint>/requests/ (POST) |
USE: Create requests for the individuals.
Params:
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
approve=true => Approves the Request in one step. Otherwise, it is left pending to approve manually through the Administration Panel
If the policy_name is not sent, the request is created without associated policy
Return:
...
Example:
| Code Block |
|---|
individual[last_name]=Gimenez%20Zapiola&
individual[email]=gomugomu%40example.com&
requests[field_1]=30707894435&
requests[approve]=true&
policy[name]=bolsas_comercio_g2 |
OnBoardingRequests
Create (POST)
| Code Block |
|---|
url = <endpoint>/requests/ (POST) |
It works the same way as the creation of normal requests but with the addition of the following parameters:
| Code Block |
|---|
"request": {
"on_boarding":"true",
"mobile_number":"+nnnnnnnnnnnnn"
} |
It returns, if success a normal request, with the addition of an origin_request in this way:
...
...
...
...
...
...
...
...
...
...
...
...
enroll_url is the URL to redirect the user in order to enroll for his certificate.
Show (GET)
| Code Block |
|---|
url = <endpoint>/requests/:origin_request_id (GET) |
It returns a request along with its data for origin_requests the same way as returned by CREATE:
SendResult (PUT)
| Code Block |
|---|
url = <endpoint>/onboardingrequests/ (PUT) |
USE: It sends the result of the onboarding process in order to approve or reject a request.
Params:
| Code Block |
|---|
:origin_request = (
:id,
:onboarding_request_id,
:onboarding_status,
:first_name,
:last_name,
:mobile_number,
:national_number_type,
:national_number
)
+:authentication_header |
id it’s the origin_request_id sent to identify the request.
onboarding_request_id it’s the OnBoarding id returned by the start request,
onboarding_status could be "autenticado" or "no autenticado"
first_name the individual first name that could have been changed.
last_name the individual last name that could have been changed.
mobile_number mobile phone number,
national_number_type document type (it doesn’t change),
national_number document number (it doesn’t change)
Passcodes
Create (POST)
| Code Block |
|---|
url = <endpoint>/passcodes/ (POST) |
USE: Create Passcodes associated with a Request (request) for an Individual. When making a new invocation, it will generate a new Passcode no matter than the previous one is still enabled and without use.
Params:
| Code Block |
|---|
:request=(:id)
+:authentication_header
|
Return:
| Code Block |
|---|
The passcode tied to the request is created and the associated passcode data is returned.
Return = headers(:access_token, :token_type, :client, :expiry, :uid) |
NOTE: If the request is executed two or more times on the same request (: id), it will generate a new pair of keys associated with each request
| Code Block |
|---|
{
"passcode_status": "enabled",
"pin_postal": "PHBXFE8H",
"pin_email": "ZK99NUY4"
}
|
Revokes
Create (POST)
| Code Block |
|---|
url = <endpoint>/revokes/ (POST) |
USE: Create a certificate revocation request
Params:
| Code Block |
|---|
:certificate=(:serial),
:policy=(:name),
:revoke=(:revocation_reason, :approve),
:individual=(
:id,
:national_number_type,
:national_number,
:first_name,
:last_name,
:email,
:birthdate,
:address,
:country,
:phone
)
+:authentication_header
|
All the parameters are optional. The system will look for the certificates that match all the provided filters. It is recommended to send more than one parameter to limit the response to the specific individual and desired certificate.
Alternative values for revocation_reason:
‘Replace’
'Key compromise'
'CA compromise'
'Affiliation changed'
'Superseded'
'Cessation of operation'
'Certificate hold'
'Remove from CRL'
'Privilege withdrawn'
'AA compromise'
'Unspecified'
Return:
If there is only one valid and non-expired certificate matched with the applied filters, a revocation request is created and returned. When success, the revoke created is returned along with HTTP code 200
| Code Block |
|---|
Return = {:id, :revocation_reason, :status, :policy_name, :individual_name,
:certificate{:serial,:data}}
Return = headers(:access_token, :token_type, :client, :expiry, :uid) |
Example:
...
In case of error code ERROR_CREATE_REVOKE (5106) is returned along with an HTTP code 400:
| Code Block |
|---|
Return = { "code": "5106", "description": "..." }
Return = headers(:access_token, :token_type, :client, :expiry, :uid)
|
Possible description values:
No certificate has been found matching the filter provided
More than one certificate match the filter provided
Not enough privileges to revoke a certificate belonging to the policy <policy_name>
There is already an open revoke
If you have more than one valid certificate matching the filter provided, the method returns an error description stating that several certificates comply with the filter. You must refine your search.
Example:
...
Search (POST)
| Code Block |
|---|
url = <endpoint>/revokes/search (POST) |
USE: return revoked certificates data
Params:
| Code Block |
|---|
:from_date=(:fecha_desde),
:to_date=(:fecha_hasta),
+:authentication_header
from_date and to_date fields format is: AAAA-MM-DD example: “2019-02-26”
|
Return:
| Code Block |
|---|
Return = :id, :revocation_reason, :status, :policy_name, :individual_name, :certificate(:serial)
Return = headers(:access_token, :token_type, :client, :expiry, :uid)
|
NOTE: The verification of the revocation status for a specific certificate must be done through the Certificates search
Alternative values for revocation_reason:
'Replace'
'Key compromise'
'CA compromise'
'Affiliation changed'
'Superseded'
'Cessation of operation'
'Certificate hold'
'Remove from CRL'
'Privilege withdrawn'
'AA compromise'
'Unspecified'
| Code Block |
|---|
{"revoke":{
"id":1,
"revocation_reason":"Unspecified",
"status":"enabled",
"policy_name":"bolsas_cereales_g2",
"individual_name":"Juan Vinsmoke",
"serial":"3BCDBA3H7QWMM8B962607"
}
}
|
Certificates
Search (POST)
| Code Block |
|---|
url = <endpoint>/certificates/search (POST) |
USE: returns Individual certificate data
Params:
| Code Block |
|---|
:certificate= (:serial, :id, :from_date, :to_date),
:policy=(:name),
:individual=(:id, :national_number_type, :national_number, :first_name, :last_name, :email, :birthdate, :address, :country, :phone)
+:authentication_header
from_date and to_date fields format is: AAAA-MM-DD example: “2019-02-26”
|
Return:
| Code Block |
|---|
= Certificate data
Return = headers(:access_token, :token_type, :client, :expiry, :uid)
|
| Code Block |
|---|
{"certificates": [
{
"id": 20,
"serial": "22190A2193BCE48A3D05B9CA67911094",
"subject_dn": "/O=Bolsa de Comercio de Rosario/OU=ROSARIO G2/OU= Empresa - 2017031705/OU=Documento – DNI16000000/CN=BCR Blanco/emailAddress=bcrblanco@bcr.com.ar",
"issuer_dn": "/C=AR/O=Bolsa de Comercio de Rosario/OU=Symantec Trust Network/OU=FOR TEST PURPOSES ONLY/CN=TEST Autoridad Certificante Bolsa de Comercio de Rosario – G2",
"not_before_date": "2017-09-17T00:00:00Z",
"not_after_date": "2018-09-17T23:59:59Z",
"individual_id": 4,
"policy_id": 2,
"created_at": "2017-09-17T20:33:23Z",
"status": "valid"
}
]
} |
...
Index (Get)
| Code Block |
|---|
url = <endpoint>/certificates/ (GET) |
USE: Returns the last 20 issued certificates
Return:
| Code Block |
|---|
Data of the last 20 certificates issued
Return = headers(:access_token, :token_type, :client, :expiry, :uid)
|
...
|
id | Internal Origin Request ID (don’t use) |
|---|---|
origin_request_id | Random Hexa number, representing the Origin-Request-ID. |
request | Request record |
app_name | name of the application used to generate this request, eg: SecureDOC. |
mechanism_request_id | value used by an external validation system to identify the validation process related to this request. This value is used, by example, for the Biometric Validation System. |
mobile_number | Mobile number used for whatsapp onboarding. |
country_mobile_code | Country code for mobile number |
enroll_url | If present, URL where the end-user must be redirected to complete the certificate enrollment. |
enroll_url could be a default one defined either for the “onboarding” mechanism (/onboarding) or another one for the “autoenroll” mechanism (/pickup). It can also be defined (via Colt Admin Console) as one of the properties for the policy:
For this field it is possible to define a template where the following variables will be replaced:
| Code Block |
|---|
[PANEL_BASE_URL]
[CURRENT_TENANT]
[ORIGIN_REQUEST_ID]
[TOKEN] |
Response Example:
| Code Block |
|---|
{
"id": 1,
"request": {
"company_name": "CertiSur S.A.",
"state": "Ciudad Autonoma de Buenos Aires",
"locality": "Ciudad Autonoma de Buenos Aires",
"id": 1,
"individual_id": 1,
"common_name": "Armando",
"national_number_type": "DNI",
"national_number": "12342342",
"country": "AR",
"first_name": "Armando",
"last_name": "33",
"status": "enabled",
"email": "jdoe@gmail.com",
"request_type": "Initial",
"approved": false,
"policy": {
"name": "acme",
"friendly_name": "Acme Firma Digital",
"validity": 365,
"verification_model": "renaper"
},
"enabled_keystores": {
"win_enh": {
"security_policy": {
"capiSecPolicy": {
"id": null,
"mask": "1"
}
}
}
},
"pin_certificate": null,
"adsec_op_type": "Initial",
"act_as_initial": false
},
"app_name": "undef_app_name",
"origin_request_id": "B2A768215FDFSDFD84D300FB8B2B9",
"mechanism": "autoenroll",
"mechanism_request_id": null,
"mechanism_status": "pending",
"token": "A88E9526F31C5DE81FDFFD8B74BE8FD256F5C",
"mobile_number": "91161590622",
"country_mobile_code": "+54",
"first_name": "Armando",
"last_name": "Carratala",
"enroll_url": "http://localhost:5003/acme/pickup?origin_request_id=B2A768215FD84D300FB8B2B9&auth_token=A88E9526F31C5DE818B74BE8FD256F5C"
} |
Show
It returns a request along with its data for origin_requests the same way as returned by CREATE.
|
|
origin_request_id is the random hexa number, representing the Origin-Request-ID.
Update
Allows updating some values or fields of a Mechanism Request.
It sends the result of the onboarding process in order to approve or reject a request.
|
|
origin_request_id is the random hexa number, representing the Origin-Request-ID.
Input parameters
|
|
All the possible fields:
app_name | name of the application used to generate this request, eg: SecureDOC. |
|---|---|
mechanism_request_id | value used by an external validation system to identify the validation process related to this request. This value is used, by example, for the Biometric Validation System. |
mechanism_status | could be ‘pending’, ‘started’, ‘completed’. When updating from ‘started’ to ‘completed’, the request gets the admin approval credits. |
mobile_number | Mobile number used for whatsapp onboarding. |
country_mobile_code | Country code for mobile number |
Revoke Request
Create
Create a revoke request
|
|
Input parameters
All the parameters are optional. The system will look for the certificates that match all the provided filters. It is recommended to send more than one parameter to limit the response to the specific individual and desired certificate.
If there is only one valid and non-expired certificate matched with the applied filters, a revocation request is created and returned.
|
|
Alternative values for revocation_reason:
‘Replace’
'Key compromise'
'CA compromise'
'Affiliation changed'
'Superseded'
'Cessation of operation'
'Certificate hold'
'Remove from CRL'
'Privilege withdrawn'
'AA compromise'
'Unspecified'
Response
If success: a HTTP(200)
|
|
Example:
If error: a HTTP(400)
|
|
Possible description values:
No certificate has been found matching the filter provided
More than one certificate matches the filter provided
Not enough privileges to revoke a certificate belonging to the policy <policy_name>
There is already an open revoke
Example:
Search
|
|
Input parameters
|
|
All the possible fields:
| Code Block |
|---|
from_date and to_date fields format is: AAAA-MM-DD example: “2019-02-26” |
The verification of the revocation status for a specific certificate must be done through the Certificates search.
Alternative values for revocation_reason:
'Replace'
'Key compromise'
'CA compromise'
'Affiliation changed'
'Superseded'
'Cessation of operation'
'Certificate hold'
'Remove from CRL'
'Privilege withdrawn'
'AA compromise'
'Unspecified'
Response
|
|
Example:
| Code Block |
|---|
{"revoke":{
"id":1,
"revocation_reason":"Unspecified",
"status":"enabled",
"policy_name":"bolsas_cereales_g2",
"individual_name":"Juan Vinsmoke",
"serial":"3BCDBA3H7QWMM8B962607"
}
}
|
Authentication Description
The following information can be useful to understand the protocol used to authenticate each endpoint.
Appendix I – Authentication Token
The Web Services authentication process is based on the token management documentation published in:
About token management
Tokens should be invalidated after each request to the API. The following diagram illustrates this concept:
During each request, a new token is generated. The access-token header that should be used in the next request is returned in the access-token header of the response to the previous request. The last request in the diagram fails because it tries to use a token that was invalidated by the previous request.
The only case where an expired token is allowed is during batch requests.
About batch requests
By default, the API updates the auth token for each request. But sometimes it's necessary to make several concurrent requests to the API, for example:
Batch request example
| Code Block |
|---|
$scope.getResourceData = function() {
$http.get('/api/restricted_resource_1').success(function(resp) {
// handle response
$scope.resource1 = resp.data;
});
$http.get('/api/restricted_resource_2').success(function(resp) {
// handle response
$scope.resource2 = resp.data;
});
}; |
In this case, it's impossible to update the access-token header for the second request with the access-token header of the first response because the second request will begin before the first one is complete. The server must allow these batches of concurrent requests to share the same auth token. This diagram illustrates how batch requests are identified by the server:
The "5 second" buffer in the diagram is the default used this API.
The following diagram details the relationship between the client, server, and access tokens used over time when dealing with batch requests:
Note that when the server identifies that a request is part of a batch request, the user's auth token is not updated. The auth token will be updated for the first request in the batch, and then that same token will be returned in the responses for each subsequent request in the batch (as shown in the diagram).