Authentication
User authentication
|
|
Input parameters
|
|
Response
|
|
| Info |
|---|
Each new request to the WS requires to include in the headers those parameters returned as HTTP response headers during the authentication with email and password. |
| Info |
|---|
New HTTP response headers are returned with each order, and those headers should be used as an authentication mechanism in the next request. |
You can find additional information on managing tokens in Appendix I – Authentication Token
Request + Mechanism
Create
|
|
Input parameters
It works the same way as the creation of requests but with the addition of the following parameters:
|
|
Response
Returns a mechanism_request record.
|
|
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).