Celiveo PIN API

*NOTE: The Celiveo WebAdmin PIN API is available from WA 8.9.123.2 onwards.

Celiveo PIN API allows customers to interface their third-party applications or scripts by passing Username and Domain parameters to generate and retrieve User PIN codes, In return a JSON with PIN is retuned.

Setup Celiveo PIN API

!Run the PowerShell Terminal in administrator mode.

1. Right-click on top of Start Button.
3. Go to your Celiveo PIN API Setup directory. Default Path: C:\Program Files\Celiveo\Celiveo 8\PinApi\powershell
4. Run .\Setup.ps1 -Port <port> Example: .\Setup.ps1 -Port 8181
5. At the end of the Setup copy the generated Authentication Bearer Token Key as marked in red as it will be necessary to access the API Endpoints.

*A 256 authentication Bearer Token Key is generated and saved at C:\Program Files\Celiveo\Celiveo 8\PinApi\config.ini, this key is necessary in order to communicate with the PIN API Services.

API Endpoints

Celiveo PIN API provides two endpoints, PIN Generation Endpoint and

PIN Endpoint, these two use Authentication Bearer Token for authorization and a JSON body payload with UserName: and Domain: information, the return call is also formatted in JSON as ID: as described below.

PIN Generation

Type	Request Format	Description
Request Endpoint	POST https://celiveo_server_hostname:port/cvoapi/genpin	PIN Generation Endpoint – Services and applications call this URI with POST to request PIN generation.
HTTP Authentication Header	Authorization: Bearer token	Replace token with the Authentication Token Key copied from the Setup or from config.ini.
JSON Body Payload	{ "UserName":"johndoe","Domain":"evolice.com" }	In this area pass the Username and Domain of the company in order to generate a PIN for defined user.
Type	Response Format	Description
JSON Response	{ "id": "PIN_value" }	Return PIN_value when the PIN is successfully generated for the provided Username and Domain.
JSON Response	{ "status": { "value": "FAILED","errorMessage":"User not found in matching directory(ies)" } }	Return message when the Username is not found in AD or SQL.
JSON Response	{ "status": { "value": "FAILED", "errorMessage": "Domain name not found" } }	Return message when the Domain is not found in AD or SQL.
JSON Response	{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "traceId": "GUID", "errors": { "Domain": [ "The Domain field is required." ], "UserName": [ The UserName field is required." ] } }	Status: 400 return message when the JSON Body Payload is malformed and does not contain Username and/or Domain.
JSON Response	{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.13","title": "Unsupported Media Type", "status": 415, "traceId": "GUID" }	Status: 415 return message when the Body Payload Media Type is not JSON or JSON is malformed.
JSON Response	HTTP/1.1 401 Unauthorized	Status: 401 The provided authorization token is not the same as the one defined in config.ini

Get PIN

Type	Request Format	Description
Request Endpoint	POST https://celiveo_server_hostname:port/cvoapi/getpin	Get PIN Endpoint – Services and applications call this URI with POST to request the User PIN.
HTTP Authentication Header	Authorization: Bearer token	Replace token with the Authentication Token Key copied from the Setup or from config.ini.
JSON Body Payload	{ "UserName":"johndoe","Domain":"evolice.com" }	In this area pass the Username and Domain of the company in order to generate a PIN for defined user.
Type	Response Format	Description
JSON Response	{ "id": "PIN_value" }	Return PIN_value when the PIN is successfully retrieved for the provided Username and Domain. Empty value will be provided if Username is not found in AD or SQL.
JSON Response	{ "status": { "value": "FAILED", "errorMessage": "Domain name not found" } }	Return message when the Domain is not found in AD or SQL.
JSON Response	{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "traceId": "GUID", "errors": { "Domain": [ "The Domain field is required." ], "UserName": [ The UserName field is required." ] } }	Status: 400 return message when the JSON Body Payload is malformed and does not contain Username and/or Domain.
JSON Response	{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.13","title": "Unsupported Media Type", "status": 415, "traceId": "GUID" }	Status: 415 return message when the Body Payload Media Type is not JSON or JSON is malformed.
JSON Response	HTTP/1.1 401 Unauthorized	Status: 401 The provided authorization token is not the same as the one defined in config.ini

HTTP Authentication

Celiveo PIN API uses an authentication scheme known as Bearer Authentication (also known as token authentication) that involves security tokens called bearer tokens that a client must send in the Authorization header when making requests to celiveo PIN API. Authorization: Bearer <token>
Further information about HTTP Authentication can be found here.

PIN API Call Examples

The following section shows examples on how to interface third-party tools with the PIN API.
Replace the <token> with token generated , server_hostname:server_port, username_value and domain_value with your data.
To execute curl go to:

1. Left-click on Start Button.
2. Type terminal and press Enter.
3. Type curl with the commands described below.
   

cURL Example to GENERATE PIN

curl -i -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <token>" -d "{"""UserName""":"""username_value""","""Domain""":"""domain_value"""}" https://server_hostname:server_port/cvoapi/genpin

cURL Example to GET PIN

curl -i -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <token>" -d "{"""UserName""":"""username_value""","""Domain""":"""domain_value"""}" https://server_hostname:server_port/cvoapi/getpin

©2024 Celiveo Pte Ltd – All Rights Reserved