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

  1. Right-click on top of Start Button.
  2. Go to your Celiveo PIN API Setup directory. Default Path: C:\Program Files\Celiveo\Celiveo 8\PinApi\powershell
  3. Run .\Setup.ps1 -Port <port> Example: .\Setup.ps1 -Port 8181
  4. 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.

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

Last modified: 14 June 2024

Feedback

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.

Post your comment on this topic.

Post Comment