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.
Additionally, the user and password must be presented. The values assigned have the following format (ask CertiSur for the values assigned to your company)
Authentication
User authentication
|
|
Input parameters
| {
"email":"{{colt_be_admin_user}}",
"password":"{{colt_be_admin_password}}"
}
|
Response
| access-token client uid |
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
Revokes
Create (POST)
url = <endpoint>/revokes/ (POST)
USE: Create a certificate revocation request
Params:
: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
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:
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)
url = <endpoint>/revokes/search (POST)
USE: return revoked certificates data
Params:
: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:
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'
{"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
$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).