CoLT - API v3
- Nestor Markowicz
- Nestor Masnatta
- Armando Carratala
Introduction
CoLT API v3 is a multitenancy web service. A tenant is an instance that is isolated from other instances and has its own data and configuration.
Endpoints are URLs providing access to the web services allowing certificate enrollment and issuance.
Homologation endpoint | |
Production endpoint |
The API is designed to establish a communication channel via SSL Client Authentication, so when establishing the HTTPS channel, you must present a valid client certificate as part of the authentication mechanism.
Certificates are considered valid when they are issued by your organization CA (pilot or prod, depending on the environment), when they are within their validity period and when they are not revoked.
Additionally, the user and password must be presented. The values assigned have the following format (ask CertiSur for the values assigned to your company).
ORGANIZATION
Email: adminXXXXX@lh2.ra
Pass: XXXXXXXOperations and notation
Every operation is accessed via a specific URL. The endpoint contains a <tenant> value.
Each organization that uses this service will access its own proprietary console via its <tenant>. Please, ask CertiSur for the value assigned to your organization. Eg <tenant>="acme"
List of <operations>
sessions
individuals
requests
passcodes
revokes
certificates
Example: https://homo-panel.certisur.com:5443/acme/api/v3/individuals/
where “acme” is the name of the tenant.
The following sections describe in detail each operation, along with its input and output parameters.
Api Version: 3.0.3.2
Authentication
User authentication
|
|
Input parameters
| {
"email":"{{colt_be_admin_user}}",
"password":"{{colt_be_admin_password}}"
} |
Response
| access-token
client
token_type
uid
expiry |
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.
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
Individuals
Search
Obtain data from an individual. A parameter is passed to it and it returns all the individuals that match the indicated parameter. If no parameter is passed, it returns all the individuals.
|
|
Input parameters
It is possible to search by null and use wildcards (%) to retrieve a specific set of individuals. Ej
|
All the possible fields:
Response
|
List
Obtain a list of the 10 last loaded individuals.
|
|
Input parameters
Response
|
Create
Create an individual.
|
|
Input parameters
Ej
|
Required fields:
Response
|
If a user exists with the same "national_number_type" and "national_number" an error with code 5105.
Enroll Request
Create
Create an Enrollment Request
|
|
Input parameters
|
The individual parameter works in the same way as the individual search and must match just one record.
The content of field_1 to field_5 depends on is Tenant.
The channel_policy_id field contains the identifier number of the Policy Keystore to assign to the request. If channel_policy_id is not sent, the Default Keystore Policy of the Policy whose “policy: { name }” is sent, is assigned to the request. If there is no Default Channel Policy associated to that Policy, the “default” keystore policy is assigned to the request.
approve equals to ‘true’ assign an approvment from the Enrollment Administrator account to a new request.
If the policy_name is not sent, the request is created without the associated policy.
All the possible fields:
Response
|
Show
It returns a request along with its data the same way as returned by CREATE.
|
|
Update
Allows updating the common_name of a Request.
|
|
common_name is generated as “<first_name> <last_name>”. The first_name and last_name of the individual will not be modified.
Input parameters
|
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:
Response Example:
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 |
Passcodes
Create
Create Passcodes associated with a Request (request) for an Individual. When making a new invocation, it will generate a new Passcode no matter if the previous one is still enabled or without use.
|
|
Input parameters
|
Response
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
|
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:
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:
Certificates
Search
Returns Individual certificate data
|
|
Input parameters
|
Alternative values for status: ‘Revoked', ‘Expired', ‘Valid'
Response
|
Example:
List
List the last 20 issued certificates.
|
|
Input parameters
none
Response
|
Enabled Keystores
(for features not associated to a request: verify, export, import)
List
Returns enabled keystores from a policy keystore with name “public” or “PUBLIC”
|
|
Input parameters
none
Response
|
All the possible fields:
keystore_name_i | Possible values: atheidp, cloud, csk, etoken, ff_nss, macos, mobile, mtoken, pkcs12, safesign, win_enh, yubikey Other values (compatibility): win_str, win_sc, vs_pta |
|---|---|
security_policy | Depends on keystore_name value (see: Security Policy ) |
Example:
Alison Desktop Configs
List
Returns Alison Desktop configs to be used within the frontend environment
|
|
Input parameters
none
Response
|
All the possible fields:
theme | Possible values: “theme1” or “theme2” |
|---|---|
language key | Possible values: “es”, “en” |
min_version | String containing the required minimum version of Alison Desktop to be used. If the required or a subsequent version is not installed a message will prompt the user to update. A min_version can be configured by feature and there is a generic min_version. |
Example:
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
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).