Initialisation

Encedo HEM needs to be initialised before it's usable. This process is called Personalisation, and these two API endpoints are dedicated to this operation.

These two endpoints are wide open and do not need any authorisation data. After the successful personalisation of the device, future calls will raise Error 406.

The format of the initialisation data is described in "General information".

Personalization

Phase 1 - challenge

Get challenge data

GET https://my.ence.do/api/auth/init

Get initial data (challenge) as the first step in the personalisation process.

Response status code

200: Operation successful

{
  "exp": 1647936471,
  "spk": "dONxxYB9mq9C3UjrVCgkAw6O30JqZkFprT55fq3ZfAM=",
  "jti": "m4M5Yn6HNoyABv+W1JiIQtSP4xiq6PBD1x5b2/PlJl8=",
  "genuine": "LH8nwNPgH3PV+zfry/Savrso/Q4=.MTY0NzkzNjQ3MQ==.MEYCIQD0GFLsc0JGDo5QoWY1m/Jcw7FKpe5kPoaRop6EWvBfhQIhALMA3DwwigtCTIL5Sopa38aWZUL4AGYUVq3u1v6f2Pjn",
  "eid": "lvVc8WGbc8m95VvUVgZO7Z1maYOPdX8Pn0cveNPtYyA="
}

403: Clock RTC not set

409: Incorrect internal state

406: Operation failed

Response data for successful operation

Name	Type	Description
eid	String	EncedoID, public key of the instance
exp	String	Expire timestamp
genuine	String	Attestation data
jti	String	Token id
spk	String	Session public key

Phase 2 - response

Upload the initial configuration

POST https://my.ence.do/api/auth/init

Upload a well-formatted initial configuration signed by the user's passphrase.

Headers

Name	Type	Description
Content-Type*	String	application/json

Request Body

Name	Type	Description
init*	String	Initialization structure

Response status code

200: Operation successful

{
  "instanceid": "e7aafede-76b1-c7c8-784b-c963967fe307",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzY29wZSI6InN5c3RlbTpjb25maWciLCJzdWIiOiJVIiwiaWF0IjoxNjQ3OTM2NDE2LCJleHAiOjE2NDc5NjUyMTYsImp0aSI6Im9JTTVZbElqYXYwRUdqQlpxVDdtbDZ3Q0d4WTRYcmpGR0lweWd6Q1lEbWM9In0.aAW7qaAjbD9y36VI0XVtO-f8l2kV0T4Y4kZZxpaAPEg",
  "genuine": "LH8nwNPgH3PV+zfry/Savrso/Q4=.MTY0NzkzNjQ3Ng==.MEQCIHJ2fARkMLCM3bb8wBImJWQMgCOCnt+x8idort0IVnP+AiA4hSYO3hV6K8/vZKAiAyiJxYMQyxHQo5qP1P2AEqEiRw=="
}

403: Clock RTC not set

406: Operation failed

409: Incorrect internal state

400: Incorrect argument(s)

401: Initialization structure validation failed

Response data for successful operation

Name	Type	Description
genuine	String	Attestation data
instanceid	String	Instance unique ID
token	String	JWT access token (referred to as JWT_TOKEN)

Log entries (directly and indirectly as indicated)

Event	Result	Source
LOG_TYPE_DEVICE_INITED	LOG_RESULT_OK	200
LOG_TYPE_STARTUP	LOG_RESULT_OK	On every powerup as second log entry (the first is LOG_TYPE_KEY_INIT)