Introduction

Throughout the documentation, the URL https://demo.utiliflex.com and port 9000 are used only as examples and will differ between different Juice deployments.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://demo.utiliflex.com:9000"
  --header "Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775"

Make sure to replace 45c7ba63-f496-4947-9315-1a3050b10775 with your API key.

Prism API uses API keys to allow access to the API. These keys are managed directly by Utiliflex Staff.

Prism expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775

You must replace 45c7ba63-f496-4947-9315-1a3050b10775 with your personal API key.

General

Check API Status

curl "https://demo.utiliflex.com:9000/ping"
  --header "Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775"

The above command returns JSON structured like this:

{
  "error": 0,
  "data": {
    "Status": "OK"
  }
}

Check the status of the API.

HTTP Request

GET https://demo.utiliflex.com:9000/ping

Check Authentication Token

curl "https://demo.utiliflex.com:9000/check-authentication"
  --header "Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775"

With a valid API token the above command returns JSON structured like this:

{
  "error": 0,
  "data": {
    "Status": "token validated"
  }
}

With an invalid API token the above command returns JSON structured like this:

{
  "error": 200,
  "error_msg": "invalid API token"
}

Verify if the API token is valid with the server.

HTTP Request

GET https://demo.utiliflex.com:9000/check-authentication

Tokens

Get Outstanding Token Requests

curl "https://demo.utiliflex.com:9000/tokens/get-outstanding?portal=test"
  --header "Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775"

The above command returns JSON structured like this:

{
  "error": 0,
  "data": {
    "token": [
      {
        "id": 1,
        "class": 0,
        "cmd": 0,
        "amount": 20,
        "time": "2019-01-22T11:18:29Z",
        "version": 4,
        "sgc":123456,
        "meter":"00000000000",
        "ti": 1,
        "ea": 7
      },
      {
        "id": 2,
        "class": 1,
        "cmd": 5,
        "amount": 0,
        "time": "2019-01-22T11:48:37Z",
        "version": 4,
        "sgc":123456,
        "meter":"00000000000",
        "ti": 1,
        "ea": 7
      },
      {
        "id": 3,
        "class": 1,
        "cmd": 1,
        "amount": 0,
        "time": "2019-01-22T11:49:46Z",
        "version": 4,
        "sgc":123456,
        "meter":"00000000000",
        "ti": 1,
        "ea": 7
      },
      {
        "id": 4,
        "class": 1,
        "cmd": 0,
        "amount": 300,
        "time": "2019-01-22T11:51:52Z",
        "version": 4,
        "sgc":123456,
        "meter":"00000000000",
        "ti": 1,
        "ea": 7
      }
    ],
    "change":[
      {
        "id":5,
        "meter":"00000000000",
        "oldsgc":123456,
        "newsgc":0,
        "oldversion":4,
        "newversion":0,
        "oldti":1,
        "newti":2,
        "ea":7
      },
      {
        "id":6,
        "meter":"00000000000",
        "oldsgc":123456,
        "newsgc":123457,
        "oldversion":4,
        "newversion":0,
        "oldti":1,
        "newti":0,
        "ea":7
      },
      {
        "id":7,
        "meter":"00000000000",
        "oldsgc":123456,
        "newsgc":0,
        "oldversion":4,
        "newversion":6,
        "oldti":1,
        "newti":0,
        "ea":7
      }
    ]
  }
}

This endpoint retrieves all outstanding token requests.

HTTP Request

GET https://demo.utiliflex.com:9000/tokens/get-outstanding?portal=<PORTAL>

Query Parameters

Parameter	Default	Description	Required
portal	""	Juice system portal to get token requests for. This parameter may appear 1 or more times in the request	Yes

Return Generated Token

curl "https://demo.utiliflex.com/tokens/callback"
  --header "Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775"
  --header "Content-Type: application/json"
  --request POST
  --data '{
    "token":[
      {
        "id":1,
        "hex":["1998FA77310C607E4"],
        "dec":["29511990995826640868"]
      },
      {
        "id":2,
        "hex":["16F28CD8C011E3380"],
        "dec":["26456622012185850752"]
      }
    ],
    "error":[
      {
        "id":3,
        "status": 200,
        "error": "error message"
      }
    ]
  }'

Return the results of a token request to the server, the body of the POST should be a JSON encoded string with the fields specified in the JSON Structure table.

HTTP Request

POST https://demo.utiliflex.com:9000/tokens/callback

JSON Structure

Field	Type	Description
token	[]api.TokenRes	A slice of api.TokenRes containing generated tokens for outstanding token requests in the system
error	[]api.Error	A slice of api.Error containing errors from the HSM for outstanding token requests in the system

api.TokenRes Structure

Field	Type	Description
id	int	The ID for the token request the provided token(s) is for
hex	[]string	A slice of strings containing the hexadecimal encoded token(s)
dec	[]string	A slice of strings containing the decimal encoded token(s)

api.Error Structure

Field	Type	Description
id	int	The ID for the token request the provided error is for
status	int	The status code from the HSM for the token request
error	string	The error from the HSM for the token request

Key Status Report

Submit New Key Status Report

curl "https://demo.utiliflex.com/key-report"
  --header "Authorization: Bearer 45c7ba63-f496-4947-9315-1a3050b10775"
  --header "Content-Type: application/json"
  --request POST
  --data '[
  {
    "sgc":123456,
    "credit":100,
    "counter":1000,
    "endDate":"2020-01-01T00:00:00Z"
  }
]'

The above command returns JSON structured like this:

{
  "error": 0
}

Submit the status of one or more vending key on the encryptor. The body of the POST should be a JSON encoded string with the fields specified in the JSON Structure table.

HTTP Request

POST https://demo.utiliflex.com:9000/key-report

JSON Structure

The following structure is wrapped within a JSON array.

Field	Type	Description
sgc	int	The SGC for the vending key
credit	int	The amount of credit available to vend with current key
counter	int	The current transaction counter for the current key
endDate	time.Time	Date until the vending key expires

Response Schema

HTTP Headers

Prism API responses will always use the following headers:

Header	Value
Cache-Control	max-age=0, private, must-revalidate
Connection	keep-alive
Content-Type	application/json; charset=utf-8
Status
X-Content-Type-Options	nosniff
Date
Content-Length

Response Body

Prism API response body will always be a JSON formatted string with the following structure:

Field	Type	Always Present
error	int	Yes
error_msg	string	No
data	object	No

If the value of the error field is > 0, then the error_msg field will be present and the data field may be omitted in the response. In contrast if the error field is 0 then the error_msg field will be omitted and the data field may be present.

The contents of the data field varies depending on what endpoint is called.

Errors

HTTP Error Codes

The Prism API uses the following HTTP error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified endpoint could not be found.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.

Prism Error Codes

The Prism API may return any of the following error codes on top of returning with one of the listed HTTP error codes.

Error Code	Meaning
100	You tried to requested an endpoint that does not exist
200	The given API key is not valid